GitHub

The GitHub connection is not decoration: how an agent hands over its work, and whether that work can be accepted, both depend on it.

Installing the app

It is installed once per workspace, not once per project.

1. "Integrations" → the "GitHub" card → "Set up" → "Install the app". Before you leave for GitHub, Quiel shows what GitHub will ask and which permissions the app gets.
2. GitHub asks where to install the app and which repositories to grant access to.
3. After installation you are returned here, and the section shows the installation together with its list of repositories.

The permissions the app requests are deliberately modest: read code, write to pull requests and comments, read checks, commit statuses and deployments (the last two are for builds and previews from Vercel, Netlify and others). There is no write access to code: the branch is pushed by the client under a human's credentials; the platform only opens the pull request and comments on it.

Quiel checks that the installation is yours in one of two ways:

• Signing in to GitHub. After installing, GitHub asks you to sign in and allow access: only an installation that your GitHub account can see is connected. For a GitHub organization, sign in as its owner.
• A fresh installation. When signing in to GitHub is not required, only an installation created no more than 10 minutes ago is accepted. An app that was installed long ago and has not been connected to any Quiel workspace yet has to be removed in your GitHub settings and installed again.

If the check does not pass, Quiel says why, and you start again with the "Install the app" button: you declined to allow the sign-in, the confirmation code expired or was already used, none of your account's installations matches, or the installation is already connected to another Quiel workspace.

The project repository

Once the workspace is connected, the project settings let you pick a repository from a list, not as a typed string.

This is not about convenience. The address used to be typed by hand, and with someone else's address you could see commits and pull requests you have no access to. The list shows only what the app actually has access to.

Repository events are accepted from the app installation that belongs to your workspace, not by a matching owner/repo name: another installation with the same name passes no events. If the app is removed on GitHub, events stop arriving until you install it again.

A monorepo: one repository, different directories

If backend and frontend live in one repository in different directories, set the repository's path inside the monorepo: the agent will then work there rather than at the root. The field sits next to the URL and the default branch.

Several repositories in one project

You can connect them, and events from all of them reach the right tasks: the platform recognises a task by the key in the branch name, not by the repository.

But a task cannot yet say which repository it writes code to. So:

• the agent receives the list of all the project's repositories and chooses for itself;
• the platform opens a pull request only when the project has one GitHub repository. With several it refuses honestly and suggests opening it by hand. It will not guess for you.

Two git modes

Set in the project settings.

The branch name is built from the project's template, with the task key and title substituted in. The task card shows which branch is in use; if a pull request is already open, it shows the real branch from it, not the one the template predicts.

The platform opens a pull request only through your workspace's app installation, one that has not been removed or suspended on GitHub. Otherwise the agent gets a scm_unavailable refusal. The work is not lost: it sits in the branch, and the pull request can be opened later or by hand.

Linking commits to tasks

A commit is linked to a task by a line at the end of its message:

Quiel-Task: ATL-42

The client adds it itself. Once pushed, the commit appears in the task card. Redelivery of the same event does not duplicate the link.

In a pull request description the platform puts the Quiel-Task line last, and anything that came from the agent (a title, paths of conflicting files) is reduced to a single line; the task key is taken from the last such line. That way the link cannot be forged through the text.

A pull request from a fork is not linked to tasks automatically: no link, no review, no acceptance on merge, and the task title is not published in it. If you work from a fork, link the pull request by hand, see Tasks.

Checks and acceptance

In the task card, below the result, sits the GitHub card: the pull request with its state and branch, and below that the checks with a "how many out of how many" summary. Checks include GitHub Actions runs and commit statuses from Vercel, Netlify and CircleCI: a failed Vercel preview build counts as a red check, just like failed tests.

Checks are shown for the branch's latest commit, not mixed together across its whole history: every push starts a new run, and the latest one is what matters.

Next to it stands the "As reported by the agent" line: what the agent itself wrote about the tests and what it linked to. That is separate information, not the same thing: an agent may write "tests skipped" while Actions are green. A gap between what is claimed and what is observed is exactly why a human looks at a task before accepting it.

When the report and CI disagree

testResult: PASSED in an agent's report is its own words about a local run. GitHub may show red on the very same commit: CI has a different environment, different secrets, different versions.

The platform now compares the two itself. If an agent delivered with PASSED while the checks on the pull request's head are red or still running, it gets told so in the delivery response, in plain words, with the names of the failing checks.

This is a warning, not a refusal: the checks may be failing for reasons that have nothing to do with this work. The hard block is the separate project setting above.

If there are no checks at all yet (the usual case, since a report arrives seconds after the push), the platform stays quiet. Passing emptiness off as "CI failed" would mean shouting in every other response.

Sending a task back when CI goes red after delivery

Checks often finish after the agent has already delivered: report arrives seconds after the push, while the run takes minutes.

The project settings have a switch, "Send the task back to the agent when GitHub checks fail". With it on: the task sits in review, the platform looks at the checks on its pull request's head every couple of minutes, and if they have completed as failures it takes the task off review and returns it to the agent the way a reviewer would, with the names of the failing checks under "Revisions after review".

While checks are still running, or absent, nothing happens: the platform simply looks again later. A task a person has already accepted drops out of sight by itself.

The switch is off until someone turns it on: the platform does not take tasks off review without explicit permission.

A broken main branch is the project's problem

When the red checks are on the repository's default branch rather than on a task branch, the breakage is shared: every task in the project will fail its checks for the same reason.

The platform used to receive those events and throw them away: they belong to no task. In a real project main did not build for days: the owner did not know, and agents took a global failure for their own mistake and went to fix someone else's problem.

Now:

• The project overview carries a banner with the names of the failing checks and links to their logs. Next to it, a "File a fix task" button opens the new-task dialog already filled in; the text can be edited.
• The agent is told in the assignment (next_task) and in the context (get_context), as its own line, not buried in JSON: the main branch is broken, this is NOT a consequence of your work, and it is not yours to fix inside this task.

The warning only covers the repository this task belongs to: a red CI in a neighbouring repository of the project is none of the agent's business.

We judge by the default branch's latest commit. A failure from two days ago that has since been fixed raises no banner: an alarm that always sounds never sounds.

A dependency whose code may not have arrived

A task counts as done by its status, not by where its code ended up. In a real project a pull request was opened on top of another task's branch: the base one was merged into main first, this one into an already-merged branch. The code never reached main, the task closed as done, and the tasks depending on it went to work on code that is not there.

A dependency is still released by status. A rule of "not merged, doesn't count" would hang, forever, the tasks of projects without pull requests: direct pushes, documentation edits, projects without GitHub. The cost of a false stall in the queue is higher than the cost of a warning someone can read.

So the platform does not change the rule. It shows the discrepancy:

• in the task card, a "code in main?" mark sits next to the dependency;
• the agent gets its own line in the assignment and in get_context: check first that the code you need is actually in the default branch, and only then build on it; if it is not there, tell a human instead of quietly restoring it.

The mark appears only when the platform knows: the task has pull requests, their base branch is known, and none was merged into the default one. No pull request, an unknown base branch, a merge that went as it should: silence. "We don't know" is not "the code isn't there".

Stacked PRs: a pull request on top of another branch

Opening a pull request on top of another task's branch is a legitimate technique: while the base one is in review, the next one is built on it. It turns into a fault in exactly one place: the base pull request is merged and GitHub does NOT retarget the dependent one: it only does that when the base branch is deleted. The merge then goes into an already-merged branch and the code never reaches the default one.

• The agent hears about it on delivery: report says its pull request is not aimed at the default branch and that retargeting is its own job.
• When the base pull request is merged, the platform reminds: a note lands in the task's feed and the project managers get a notification listing what needs retargeting.

The platform does not retarget anything itself. That is a write to someone else's repository, and the app deliberately has no such right. It is also, often, a deliberate choice: a chain of three pull requests is merged one at a time, and retargeting the middle one is premature.

Auto-acceptance on merge

Auto-acceptance is enabled in the project settings: when the pull request is merged, the task moves to "Done" by itself.

Turn it on if your review happens in GitHub anyway. Otherwise you get two acceptances in a row. If review is done in Quiel, leave it off.

Branches after merge

Every task gets its own branch. After a merge they stay behind, and a hundred tasks later the repository's branch list is hard to search.

GitHub has a setting for this: Automatically delete head branches in the repository settings. With it on, the branch is deleted as soon as the pull request is merged; a pull request closed without merging keeps its branch, which is right: it holds the only copy of that work.

Quiel shows, in the project settings, whether your connected repositories have it on, and links to where it is changed. It does not delete branches itself: that would require permission to write to any branch, including the default one, which is out of proportion for tidying up. It is also your call, not ours: for teams with stacked pull requests or their own retention policy, a branch deleted by an outside app raises questions.

Tasks from GitHub Issues

An issue can be turned into a project task: the title, body and labels come across. A back-link remains, so it is clear where the task came from.