Connect GitHub to Qoren

Connect GitHub once with a fine-grained personal access token and your agents can wake when an issue is opened or labeled, someone comments, a pull request is opened, reviewed or merged, code is pushed, a release ships or a workflow run fails. Qoren creates the GitHub webhooks itself, so there is no URL or secret to copy.

The same connection lets the agents you choose search and read issues and pull requests and, if you allow it, comment, open issues and add labels. Closing and merging always wait for your approval. How connections, access and approvals fit together is in connect your tools with Integrations.

Before you start#

• You are the owner of your Qoren organization. Only the owner connects tools, gives agents access and sends connect links.
• Integrations is on for your account. It is rolling out: if the sidebar has no Integrations under Capabilities, it is not on your account yet.
• For triggers on a repository, your GitHub account is an admin of it. For triggers on every repository of an organization, you are an owner of the organization. GitHub only lets admins and owners add webhooks.
• One token covers one resource owner: your own account or one organization. For repositories under two owners, make two tokens and connect each one.

Make the key#

1. In GitHub, open Settings, Developer settings, Personal access tokens, Fine-grained tokens and choose Generate new token (open it in GitHub).
2. Name it Qoren.
3. Set the Resource owner to the account or organization that owns the repositories.
4. Choose Only select repositories and pick the ones your agents should work on.
5. Under Repository permissions, give:

• Webhooks: Read and write, so Qoren can set up triggers.
• Issues, Pull requests or Contents: Read only. Choose Read and write only if agents should comment, open issues or add labels.
• Everything else: No access.

6. For triggers on a whole organization, an organization owner gives Organization permissions, Webhooks: Read and write instead.
7. Pick an expiry date. Qoren reminds you before it lapses when GitHub tells it the date.
8. Generate the token and copy it. GitHub shows it once.

A classic token (it starts with ghp_) also works, but it reaches every repository you can. Qoren notes this when it checks the key; a fine-grained token limited to the repositories you need is safer.

Connect it in Qoren#

1. In the sidebar, under Capabilities, click Integrations.
2. Under Add a tool, click GitHub. The Connect GitHub dialog shows the same steps as above.
3. If you run an agency, choose the client in Which client is this for?, or leave No client (your own account).
4. Paste the token into Personal access token.
5. In Repository or organization, type the repository as owner/repository (for example acme/website), or just an organization name for every repository in it. It is optional, but triggers need it.
6. Click Check key. Under Key checked you see the account, Can read, how many webhooks are left for the busiest event (out of 20) and, when GitHub reports it, when the token expires.
7. Under What agents may do, choose Read only or Read and write.
8. Click Connect.

The screens are shown step by step in connect a tool.

What Qoren checks#

• That the token is valid, on GitHub's rate limit endpoint, which costs nothing.
• Who it belongs to. The account's login becomes the label, with the repository after it when you named one.
• That it can see the repository or organization you named. If GitHub cannot find it for this token, the key is refused with that reason. GitHub answers "not found" rather than "forbidden" for a private repository a token cannot see, so check the name and the token's repository list.
• Whether you are an admin of the repository. If not, the check notes that only admins can add webhooks there.
• Whether the token can read the webhooks there, and how many already listen for the busiest event. If it cannot, the check says to give it Webhooks: Read and write.
• When the token expires, when GitHub sends that date. Fine-grained tokens can have no expiry, and GitHub does not always report it.

Whether the token can write is not checked up front: a write tool that GitHub refuses fails with a clear message instead.

Give an agent access#

A new connection is used by no agent until you give one access. Open the connection under Connected, choose an agent (or all agents) in Give access to…, pick Read only or Read and write, and click Give access. See give an agent access.

Events#

Create triggers from these on the agent's Triggers tab; see wake an agent from a connected tool. For a step-by-step trigger recipe, see wake an agent from GitHub.

What the agent receives. The event, the action, the repository and whether it is private, who did it, and a short summary of the issue, pull request, comment, review, release or workflow run, with long text shortened.

How the webhook is set up. Qoren creates one GitHub webhook per GitHub event it needs (for example one for issues) on the repository or organization you named, signed with a secret only Qoren and GitHub know. Triggers that need the same GitHub event share it. Which of your triggers a delivery matches is read from the signed body, never from an unsigned header.

GitHub allows 20 webhooks per event on a repository or organization. Qoren counts them first (a webhook that sends every event counts for each one). If there is no room, the trigger is not created and you are told to delete a webhook you no longer use. Qoren never removes a webhook it did not create.

Tools agents can use#

Only your repositories. A fine-grained token can read any public repository on GitHub, so Qoren only lets a tool act on repositories of the connection's owner. Pointing a tool at someone else's repository is refused and nothing is done.

Comments in public repositories count as outbound. Comment and Open an issue on a public repository publish text anyone can read. After an agent has read data from any connection, those two wait for your approval for 30 minutes on public repositories; on a private repository they follow the agent's usual settings. See outbound sends after a read. Closing and merging always wait on the Approvals page.

Limits and gotchas#

• One resource owner per token. A token made for your account cannot reach an organization's repositories, and the other way round.
• Admin or owner for triggers. Repository webhooks need a repository admin; organization webhooks need an organization owner's token with Organization permissions, Webhooks: Read and write.
• Token expiry is best effort. When GitHub reports an expiry date, Qoren shows it on the connection and emails you 14 and 3 days before it lapses. See key expiry reminders. A token with no expiry, or one GitHub does not report, gets no reminder.
• GitHub never retries a failed delivery. Qoren's daily check asks GitHub to redeliver deliveries of the last three days that never got through, at most 50 per webhook each day, and recognises any it already handled, so nothing runs twice.
• The daily check repairs webhooks. One that was deleted, switched off, pointed elsewhere or stopped sending the event is set up again.
• GitHub deletes tokens that sit unused for a year.

Troubleshooting#

• "This token cannot see owner/repository." Check the spelling, and that the token's Only select repositories includes it under the right resource owner.
• "Name the repository as owner/repository." Use the form acme/website, or just acme for a whole organization.
• "This token cannot manage webhooks on …" Give the token Webhooks: Read and write, from an account that is an admin of the repository (or an organization owner for organization webhooks), then use Replace key.
• "Name the repository (owner/repository) or organization this GitHub connection watches before adding a trigger." You connected without a repository. Click Replace key, paste the token again and fill in Repository or organization.
• "… already has 20 webhooks for … events." Delete a webhook you no longer use in the repository's Settings, Webhooks, then try again.
• The connection says Needs a new key. The token expired or was deleted. Its triggers are paused until you click Replace key and paste a new one. See when a connected tool stops working.

Disconnect and delete the token#

1. On the Integrations page, open the GitHub connection under Connected.
2. Click Disconnect, then Disconnect again in the Disconnect GitHub? dialog (or Keep it).

Qoren deletes the stored token, removes the webhooks it created on your repository or organization, removes every agent's access and pauses the triggers that used the connection.

Qoren cannot revoke a GitHub token, so delete it in GitHub too: open Settings, Developer settings, Personal access tokens and delete the token (open it in GitHub).