> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Sync tk issues with GitHub Issues

# GitHub Integration

Sync your tk issues bidirectionally with [GitHub Issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/learning-about-issues/about-issues). Keep your local Markdown issues in sync with GitHub's issue tracker.

***

## Setup

### 1. Create a GitHub Token

Create a [Personal Access Token](https://github.com/settings/tokens) with `repo` scope.

### 2. Configure tk

```bash theme={null}
tk config set github.token ghp_your_token_here
tk config set github.repo owner/repo
```

Or use environment variables:

```bash theme={null}
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_REPO=owner/repo
```

***

## Sync Issues

### Pull from GitHub

Import GitHub Issues into tk:

```bash theme={null}
tk github sync --pull
```

This creates `.tickets/` files for each GitHub Issue.

### Push to GitHub

Push local tk issues to GitHub:

```bash theme={null}
tk github sync --push
```

### Bidirectional Sync

Sync both directions:

```bash theme={null}
tk github sync
```

***

## Mapping

| tk Field         | GitHub Field       |
| ---------------- | ------------------ |
| `title`          | Issue title        |
| `description`    | Issue body         |
| `status: open`   | Open issue         |
| `status: closed` | Closed issue       |
| `labels`         | Labels             |
| `priority`       | `priority:N` label |
| `type`           | `type:X` label     |

***

## Check Status

View sync status and any conflicts:

```bash theme={null}
tk github status
```

***

## Configuration Options

```bash theme={null}
# Set GitHub token
tk config set github.token <TOKEN>

# Set repository
tk config set github.repo owner/repo

# Set label prefix (default: none)
tk config set github.label_prefix "tk:"
```

***

## Workflow Example

```bash theme={null}
# Initial import from GitHub
tk github sync --pull

# Work locally, create issues
tk create "New feature" -t feature

# Sync changes back
tk github sync --push

# Regular bidirectional sync
tk github sync
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    Verify your token has `repo` scope and is correctly configured:

    ```bash theme={null}
    tk config get github.token
    ```
  </Accordion>

  <Accordion title="Repository not found">
    Check the repo is set correctly:

    ```bash theme={null}
    tk config get github.repo
    ```

    Format should be `owner/repo`.
  </Accordion>

  <Accordion title="Sync conflicts">
    Run `tk github status` to see conflicts. Resolve by choosing which version to keep.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Linear Sync" icon="square-kanban" href="/integrations/linear">
    Sync with Linear for team workflows.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli-reference/commands">
    Full command documentation.
  </Card>
</CardGroup>