Connect to GitHub
Connecting GitHub means you can delegate straight from your board: tag an issue with cate and a Cate agent handles it. Everything they do contributes to collective context: specs, decisions, handoff comments, and research visible to teammates and their agents.
An agent walks you through the setup and helps you merge .cate/workflows.json — your tracker configuration file — to your default branch.
Before you start
Section titled “Before you start”Add your GitHub credentials in Settings → Accounts. Use a Personal Access Token or OAuth.
The gh CLI is strongly recommended. The agent uses it to create boards, add status columns, and link repositories. Without it, some steps require manual action in the GitHub web UI. Install it from cli.github.com and run gh auth login before starting.
If your project needs different credentials than your global settings, see Project-specific credentials.
Run the connect flow
Section titled “Run the connect flow”Click New Task in the top right, then Configure → GitHub. If GitHub isn’t available, check that your GitHub credentials are set in Settings → Accounts.
The agent checks your git remote, then walks you through:
-
Board selection — connect an existing GitHub Projects board or create a new one. If creating, the agent provisions the board, adds status columns, and links the repository automatically.
-
Status columns — the agent maps your board’s status columns to Cate’s queues. You can have any statuses you want — Cate recommends a set of five, but works with your existing board. See Status lifecycle for details on how statuses map to queues.
-
Configuration — the agent asks about your dispatch label, branch naming convention, and autonomy preference, then writes everything to
.cate/workflows.json. -
Dispatch label — a GitHub label (default:
cate) applied to issues so agents know which ones to work on. The agent creates it for you.
After connecting
Section titled “After connecting”The agent commits the configuration and ensures it reaches your default branch. Once merged, the app picks up the new tracker automatically.
To adjust the configuration later, start a Pair session and ask the agent to help. See the workflows.json reference for field descriptions.
Project-specific credentials
Section titled “Project-specific credentials”If this project needs different credentials than your global settings — for example, a different GitHub account — click the project settings gear (top right) and set them under the project’s credential overrides.
Troubleshooting
Section titled “Troubleshooting”Expired or revoked token. Generate a new PAT and update it in Settings → Accounts. See Credentials for details.
Missing token scopes. Check your token’s scopes in GitHub → Settings → Developer Settings → Personal access tokens. Required scopes: repo, project, and read:org (for organization repositories). Regenerate with the correct scopes and update in Cate.
Board deleted or reconfigured. Check tracker.projectNumber in .cate/workflows.json against your actual board. Update the file if they don’t match, or re-run setup.