Credentials

Cate needs credentials to interact with your issue tracker. For GitHub, this is a personal access token (PAT). For Jira, it’s your email address and an API token. Credentials are stored securely on your machine and never written to the repository.

GitHub credentials

Required token scopes

Your GitHub PAT needs the following scopes:

• repo — read and write access to repositories (code, issues, PRs)
• project — read and write access to GitHub Projects boards
• read:org — required if you are using organization repositories

Create a token

1. Go to GitHub -> Settings -> Developer Settings -> Personal access tokens
2. Click Generate new token (classic)
3. Select the required scopes above
4. Copy the token immediately — GitHub shows it only once

Configure in Cate

Open Settings from the Cate dashboard, select Issue Tracker, and enter your GitHub token. Cate validates the token against the GitHub API before saving.

You can configure a global token (used for all repositories) or per-repository tokens (useful when you have repositories under different accounts or organizations with different access levels).

Jira credentials

Jira uses email address and API token authentication rather than a personal access token.

Create a Jira API token

1. Go to id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a descriptive name (for example, “Cate”)
4. Copy the token immediately

Configure in Cate

Open Settings from the Cate dashboard, select Issue Tracker, choose Jira, and enter:

• Site URL — your Jira site (for example, mycompany.atlassian.net)
• Email — the email address for your Atlassian account
• API token — the token you just created

Cate validates the credentials by connecting to your Jira instance before saving.

Credential storage

Cate stores credentials using your operating system’s secure credential store:

Platform	Storage
macOS	macOS Keychain
Windows	Windows Credential Manager
Linux	libsecret (GNOME Keyring, KWallet, or similar)

If secure storage is unavailable, Cate falls back to encrypted local storage.

Credentials are never written to .cate/workflows.json, committed to your repository, or transmitted anywhere other than the issue tracker API.

Rotating credentials

To rotate a token:

1. Generate a new token in GitHub or Jira
2. Open Settings -> Issue Tracker in Cate
3. Enter the new token and save

Cate uses the new credentials immediately on the next API call — no restart required.

Troubleshooting

If Cate reports a credential error, check:

• The token has not expired and has the required scopes
• The Jira site URL is correct (no trailing slash, no https:// prefix — just mycompany.atlassian.net)
• The Jira email matches the account that owns the API token

See Tracker connection failed for detailed troubleshooting steps.