Skip to content

Branches and pull requests

How a task reaches your base branch, by direct commit or one branch and pull request per task, how merges are detected, and what failed and blocked mean.

Publish modes

What Publish does on a task depends on the project's repository and its Publish mode setting, which an Admin or Owner sets in Settings > Git.

ModeWhat Publish doesWhen the task lands
No repositoryNothing in Git.At once (Published without git).
Direct commitCommits the render on the base branch.Once the commit is made.
Pull requestCommits to the task's branch and opens or updates its pull request.When the pull request merges.

One branch per task

A task keeps the branch of its first pull request for its whole life: spec/<project key>/t-<n>-<slug>, such as spec/shop/t-4-reserve-stock. A task with a tracker key carries it in front, as in spec/shop/KAN-43-t-4-reserve-stock.

  • Recorded before the first push. Renaming the task does not move its branch.
  • Reused by every attempt. Retry, Publish again and a publish after the agreement changed all update the same branch, and reuse the pull request while it is open.
  • Never taken over. A first attempt never takes over a branch that already exists.

The pull request is titled spec: T-4 <name>. A task with a tracker key titles it KAN-43 spec: T-4 <name>, and the body links the task and lists the decisions of its answered questions.

Detecting the merge

SpecsGraph asks GitHub or GitLab about every pull request waiting to merge every five minutes, each on its own, so one provider error never stops the others. Check now on the task asks at once. The merge lands the task from the tree the merge produced, so the files that landed are exactly what Git has.

Note

Artefacts are held while a pull request waits

Another task that scopes one of the same artefacts cannot publish until the pull request merges or closes.

States and what to do

StateMeaningWhat to do
PublishingThe job runs.Wait.
Awaiting mergeThe pull request is open.Review and merge it, then choose Check now.
PublishedLanded on Main for the current agreement.Nothing: the task moves to Done by itself.
OutdatedLanded for an older agreement.Publish again.
FailedThe job failed, or the pull request was closed without merging.Retry.
BlockedSomething must change first.See Blocked reasons.

Tasks and publishing covers the task's own states, from Draft to Done.

Blocked reasons

  • Files changed in the repository (external edit). A file SpecsGraph would overwrite was changed in Git, and the message names the files. An Admin can choose Overwrite, which takes Git's current files as known and publishes again over them. The overwrite is recorded.
  • No access. SpecsGraph cannot write to the repository. Fix the connection, as described in Connect GitHub or GitLab.
  • Render collision. Two artefacts would write one file. Rename one of them.
  • Main moved. Main changed since the publish was planned. Publish again.

An archived project also blocks publishing. Troubleshooting lists other problems and their fixes.

Abandoning a task

Abandon closes the task's open pull request and, shortly after, deletes its branch. A pull request merged before the close still lands, so Git and Main never disagree.

Next steps