← back

Connect GitHub for issue creation

okro can file GitHub issues into your repository straight from a domain’s readiness findings — one issue listing the fixes that would raise your AI-visibility score. Each domain links to its own repo and its own token, so different sites can point at different repos.

okro only ever creates issues. It never reads your code, never pushes commits, and never opens pull requests through this connection. The token you provide must be restricted to Issues only — the steps below produce exactly that.

1. Create a fine-grained token (Issues-only)

Use a fine-grained personal access token (not a classic token — classic tokens can’t be scoped to a single permission).

1. GitHub → your avatar → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
2. Token name: e.g. okro issues – acme.com.
3. Resource owner: the account or organization that owns the repo.
4. Expiration: pick a limited lifetime (e.g. 90 days) and rotate when it lapses.
5. Repository access: choose Only select repositories and select the one repo for this domain. Do not grant access to all repositories.
6. Permissions → Repository permissions: set Issues to Read and write. Leave every other permission at “No access.” Issues-write is the only permission okro needs.
7. Click Generate token and copy it — it starts with github_pat_…. You won’t see it again.

Least privilege: with only Issues: Read and write on one repo, the worst a leaked token could do is open or edit issues in that single repo — it cannot touch your code, secrets, or other repositories.

2. Connect it in okro

1. Open the domain in okro (its site page).
2. In the GitHub issues card, enter the repository URL (e.g. https://github.com/acme/website or acme/website) and the token you just created.
3. Save. okro stores the token encrypted at rest and never displays it again — the card only shows the connected repo.

3. File an issue

On the domain’s page, click File GitHub issue. okro opens one issue in the connected repo summarizing the current failing readiness checks (with the evidence for each) and links you to it. Your team triages and fixes from there.

Managing the connection

• Rotate the token: generate a new fine-grained token and re-save it in the card.
• Disconnect: use Disconnect in the card, and/or revoke the token in GitHub → Developer settings.
• Per domain: each domain has its own repo + token; connecting one doesn’t affect the others.

Troubleshooting

“GitHub rejected the request” — the token is missing Issues: Read and write, doesn’t have access to that repo, has expired, or the repository URL is wrong. Re-check step 1 and the URL.