Skip to main content

​
GitHub Integration

Sync your tk issues bidirectionally with GitHub Issues. Keep your local Markdown issues in sync with GitHub’s issue tracker.

​
Setup

​
1. Create a GitHub Token

Create a Personal Access Token with repo scope.

​
2. Configure tk

tk config set github.token ghp_your_token_here
tk config set github.repo owner/repo
Or use environment variables: 
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_REPO=owner/repo

​
Sync Issues

​
Pull from GitHub

Import GitHub Issues into tk: 
tk github sync --pull
This creates .tickets/ files for each GitHub Issue.

​
Push to GitHub

Push local tk issues to GitHub: 
tk github sync --push

​
Bidirectional Sync

Sync both directions: 
tk github sync

​
Mapping

tk FieldGitHub Field
titleIssue title
descriptionIssue body
status: openOpen issue
status: closedClosed issue
labelsLabels
prioritypriority:N label
typetype:X label

​
Check Status

View sync status and any conflicts: 
tk github status

​
Configuration Options

# 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

# 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

Verify your token has repo scope and is correctly configured:
tk config get github.token
Check the repo is set correctly:
tk config get github.repo
Format should be owner/repo.
Run tk github status to see conflicts. Resolve by choosing which version to keep.

​
Next Steps

Linear Sync

Sync with Linear for team workflows.

CLI Reference

Full command documentation.