Connect to Jira
Connecting Jira 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 — Jira needs to reference pull requests. Then add your Jira credentials: your email, an API token, and your site URL (e.g., yourteam.atlassian.net). Create an API token at id.atlassian.com/manage-profile/security/api-tokens.
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 → Jira. If Jira isn’t available, check that your Jira credentials are set in Settings → Accounts.
The agent checks your git remote, then walks you through:
-
Project and board selection — the agent discovers your Jira projects and boards. Select the project and board you want Cate to use. Scrum and Kanban boards are both supported.
-
Status mapping — the agent maps your existing Jira workflow statuses to Cate’s queues. You can have any statuses you want — Cate recommends a set of five, but works with your existing workflow. 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.
Board type notes
Section titled “Board type notes”Scrum boards — Cate scopes work to the active sprint and assigns new issues to it automatically.
Kanban boards — Issues created via the API land in the Jira backlog, not on the board. You’ll need to move them to the board manually, or set up a Jira automation rule to do it automatically.
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 or Jira site — 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 API token at id.atlassian.com/manage-profile/security/api-tokens and update it in Settings → Accounts. See Credentials for details.
Invalid credentials. Verify the site URL has no https:// prefix and no trailing slash — just mycompany.atlassian.net. Confirm the email matches the Atlassian account that owns the API token.
Board deleted or reconfigured. Check tracker.jira.boardId in .cate/workflows.json against your actual board. Update the file if they don’t match, or re-run setup.