Agents and GitHub
Applies to: Hosted session and Your runner.
When you hand a task to a coding agent, the agent does its work on GitHub: it pushes a branch, opens a pull request, and then responds to what reviewers and CI say about it. This page describes that side of the loop.
It assumes GitHub is already connected for the workspace. For connecting the App, choosing repositories, and the linking and status-sync mechanics that are shared with GitLab and Bitbucket, see GitHub and Git linking, status sync, and branch names.
For the task-side view of a run (the timeline, the cost, the states a task moves through) see Tasks and pull requests.
The agent works as the App bot
An agent does not use your GitHub account, and it does not need one of its own.
When the delegate agent asks Ithura for credentials, it gets a short-lived GitHub App installation token, limited to a single repository, carrying contents and pull-requests write access, and valid for at most an hour. It also gets the App bot's git identity.
So the branch, the commits and the pull request are all authored by
<app>[bot], and you review them the way you would review anyone else's work.
Because the pull request is not yours, you can approve it or request changes on
it yourself, which you could not do on your own pull request.
Only the delegate's own API token can request these credentials, and the token is never stored and never logged.
How an agent gets them
- A hosted session needs nothing. The agent only pushes its branch, and Ithura opens or updates the pull request as the App bot. See Hosted agent sessions.
- A webhook runner finds them in its dispatch payload, in a
githubblock filled in just before the run is sent. See Your runner for that block. - A token agent, meaning one that calls the Ithura API with its own token,
asks for them with
POST .../issues/{id}/delegation/github-token/. Only the task's own delegate may ask. Every request is in the audit log asissue.delegation.github_token.
Which repository the token is for
A token is good for one repository, so Ithura has to pick one. In order: the repository you passed, which has to be connected to the workspace; the repository of a pull request already linked to the task; or, failing both, the workspace's only connected repository.
With several connected repositories and nothing to go on, there is no answer to guess at, so the request is refused rather than picking one: "No GitHub repository for this task: pass repo, or connect exactly one repository". Asking for a repository that is not connected to the workspace is refused too.
What sends a task back to the agent
Four things put a task that is with an agent back into working, with the feedback attached so the agent picks it up on its next pass.
| What happens on GitHub | When it sends the task back |
|---|---|
| A review requesting changes | Always |
| A review left as a comment | When the comment mentions the App |
| A pull request comment | When the comment mentions the App |
| A check suite | When it failed on the pull request's current head commit, up to three times per pull request |
| The branch conflicting with its base | Always, found by the reconciler (see below) |
A review that approves the pull request is noted on the task and does not send it back, because there is nothing to fix.
A review that requests changes comes back with the review text and every line
comment, each as file:line: comment. A failing suite comes back with each
failed check, its link and its summary.
Every piece of feedback is recorded once, so a webhook GitHub delivers twice is a no-op rather than a second round.
Failing checks are retried three times
After three automatic fix attempts on the same pull request, Ithura stops sending a failing suite back. The pull request stays in review and the task says what happened: "checks on PR #301 still fail after 3 automatic fix attempts, so Builder stopped retrying".
An agent that cannot get a suite green in three tries is usually not going to get it green in thirty, and the attempts cost money each time.
Mentioning the App means writing @<app-slug> or @<app-slug>[bot] in the
comment, so a reviewer can steer the agent in the place they are already
reviewing: "@ithura the lint error is in the test file too".
Only people with write access can steer an agent
An event sends the task back only when its author is an OWNER, MEMBER or COLLABORATOR of the repository. Anyone else can comment, and the team will see it, but it does not reach the agent. See Comments from outside the team.
Nothing the App's bot writes ever triggers the loop, and neither does any other bot account. This is what stops an agent replying to itself, or two pieces of automation talking to each other in a circle.
Conflicts are found by polling, not by a webhook
GitHub never sends an event when a pull request starts conflicting with its base. A branch that merged cleanly this morning can be conflicted by lunchtime because something else landed, and no webhook will say so.
So Ithura re-reads the open pull requests of tasks that are with an agent (working or in review) every five minutes. A conflicted branch sends the task back with a feedback item telling the agent to update the branch from its base, resolve the conflicts, check that the tests still pass, and push.
That item is recorded once per head and base commit pair, so it does not repeat until something actually changes.
The same pass is the backstop for lost webhooks. If the App had an outage, a subscription was missing, or a deploy landed while GitHub was retrying, a status that moved on GitHub (merged, closed, drafted, marked ready) is picked up here and the task follows exactly as if the webhook had arrived.
Practically: a conflict or a missed event is noticed within about five minutes, not instantly.
Comments from outside the team
Someone with no write access comments on a pull request an agent is working on. A user of your product, a passer-by in a public repository, anyone.
Their comment is shown to your team and never given to the agent:
- The text is stored as a task comment marked as coming from GitHub, and in the outside-comments record.
- It is never written to the agent's feedback, and
agent/workleaves it out, so it cannot become an instruction. - If the task has an agent thread in chat, a line appears there too, with a link to the comment on GitHub.
The App bot also thanks the author on the pull request, so a drive-by report does not sit there looking ignored. One thank-you covers that author on that pull request for 24 hours, rather than replying to every comment they leave.
A workspace admin can turn the thank-you off in the GitHub integration settings. It is on unless you turn it off, and turning it off changes only the reply: the comment still reaches the team the same way.
If something in an outside comment should reach the agent, a team member passes it along through a trusted path: a mention on the pull request from an account with write access, or the agent thread on the task.
Why it works this way: an agent that took instructions from any commenter would be an injection hole with a public URL. Keeping outside text out of the agent's input entirely, rather than trying to filter it, leaves no bypass to find.
Linking a plain GitHub issue
Not everything starts as a pull request. A task can also link a GitHub issue, by its URL:
https://github.com/{owner}/{repo}/issues/{number}
The link records what the issue is and keeps that up to date. Pasting a pull request URL here is rejected with a message saying so, since a pull request links as a pull request.
If your workspace is connected to GitHub Enterprise Server, paste the issue URL from that server.
Linking fails with a clear reason when GitHub is not connected for the workspace, when the installation cannot see that repository, or when there is no such issue.
On the task, Linked issues sits under Linked pull requests. Use Link GitHub issue and paste the URL. Each row shows the repository and number, the title, whether it is open or closed, a link out, and an unlink button. Whoever can link a pull request can link an issue.
Four things to know:
- Linking is manual only. A pull request auto-links from its branch name or title; an issue has neither, so there is nothing to match on.
- An issue link never starts or ends agent work. Closing the issue does not move the task.
- The title and state refresh when the task is opened, at most every ten minutes per link. If the App is subscribed to the Issues event they update as soon as they change.
- Comments on a linked issue follow the outside-comment rules above, including the thank-you and the setting that turns it off. With one difference: a comment from someone with write access is brought in as an ordinary task comment, with no "not from the team" mark, no thank-you and no line in the agent thread. It is still never given to the agent.
When GitHub needs permissions approved
The App's permissions change as features are added. GitHub does not grant new permissions automatically: an owner of the installation has to accept them.
Until that happens, workspace admins see a notice in the GitHub integration settings naming exactly which permissions are short, what each one needs, and what it currently has, with a link to the page on GitHub that accepts them.
The notice says plainly what is switched off in the meantime: agent pull requests, CI feedback and issue replies. Only admins see it, and it is not shown at all when nothing is missing.
The permissions involved are repository contents, issues, pull requests, checks, and repository metadata.
Troubleshooting
An agent is not pushing or opening pull requests. Check the GitHub card in workspace settings for the permissions notice above. That is the usual cause, and it disables exactly these features.
A reviewer asked for changes and nothing happened. Check the reviewer's access to the repository. Only OWNER, MEMBER and COLLABORATOR reviews steer an agent. A review from outside that set reaches the team but not the agent.
A comment mentioning the agent did nothing. Check the spelling of the App slug, and check the commenter's repository access. Both have to hold.
CI failed but the task did not move. The failed suite has to be on the pull request's current head commit. A failure against an older commit is not a reason to send the task back, since the branch has already moved on.
A conflict took a few minutes to register. That is expected. Conflicts are found by the five-minute reconciler described above, because GitHub sends no event for them.