Task status on pull requests

CodeHerder can show a task’s state on the pull or merge request that the task opened. It has two ways to do this:

• The status check is on by default. CodeHerder posts a check named CodeHerder to your git host.
• The status badge is off by default. It is a small image in the description of the pull or merge request.

Both show only a fixed set of words. They never show the task title, the workspace, people, agent names, costs, or the text of a comment or blocker.

Read this before you require the check

On GitHub, do not add CodeHerder to your branch protection’s required checks. The check is green only when the task is done. A task reaches done after the merge stage, so a required check would stop CodeHerder from merging its own pull request. Leave it as an optional check. See Should you require it?.

What the check shows

The check is named CodeHerder. Its title is CodeHerder: <stage>. Its text is the stage, or the stage and the reason the task waits. For example:

review · needs your answer

The Details link opens the task in CodeHerder.

Stage words

Word	Meaning
plan	The task is planning or triaging.
code	The task is being built.
review	The task is in review.
merge	The task is merging.
verify	The task is being verified after the merge.
done	The task is finished.
cancelled	The task is cancelled.

A stage you named yourself shows as todo, in progress or done, depending on what kind of stage it is. A blocked task shows the stage it left.

Why a task waits

When a task waits, the text adds one reason after the stage. If more than one reason applies, CodeHerder shows the first in this list:

Reason	Meaning
needs your answer	An agent asked a question and a person has not answered. See When an agent needs your input.
waiting on dependency	The task waits for another task. See Blockers.
release wait	The agent stopped and waits for new input.
in review	A move to the next stage waits for a person to approve it. See Approvals.
paused	Any other hold on the task.

State on your git host

What the task is doing	GitHub check run	GitHub commit status	GitLab commit status
Working	In progress	Pending	Skipped
Waiting for something that clears itself	Queued	Pending	Skipped
Waiting for a person	Action required	Failure	Skipped
Done	Success	Success	Success
Cancelled	Cancelled	Error	Skipped

Only done is a success. A task in merge or verify still shows as working, because its checks have not passed yet.

CodeHerder posts nothing for a task that has not started or that is archived. A check that is already there stays as it was.

GitHub gets a check run when the installation has the Checks permission. It gets a commit status when the installation only has Commit statuses.

When it updates

The check changes when the task changes stage, when an approval, blocker or question changes, and when a new commit lands on the branch. CodeHerder also refreshes it every 10 minutes while the task is in progress. If your git host is down, CodeHerder tries again later.

Should you require it?

GitHub. Keep CodeHerder out of the required checks. A required check that is not yet green blocks the merge stage, and the check turns green only after that stage.

GitLab. You can leave Pipelines must succeed on. CodeHerder posts skipped until the task is done, and a skipped status does not hold a merge.

Permissions

• GitHub App. The installation needs Checks: Read and write, or Commit statuses: Read and write. An owner of the organization must accept new permissions on the installation. CodeHerder tries again within an hour. See Connecting the GitHub App.
• A repository with no App installation. The workspace GitHub token needs Commit statuses: Read and write. See Integrations.
• GitLab. The workspace GitLab token needs the api scope.

Turn the check off

Only a workspace owner or admin can change this.

1. Open Settings → General.
2. Find PR status checks.
3. Clear Post a CodeHerder status check on pull and merge requests.

Or run:

ch workspace edit <workspace> --pr-status-checks false

Use true to turn it back on. The setting applies to that workspace only. A group does not pass it down to its workspaces, and a group’s settings page does not show it. Turning the check off leaves existing checks as they are.

The status badge

The badge is an image that shows the same stage and reason as the check. Turn it on if you want the state in the description of the pull or merge request, and not only in its checks.

Turn the badge on or off

Only a workspace owner or admin can change this.

1. Open Settings → General.
2. Find PR status badge.
3. Select Add a status badge to pull and merge request descriptions.

Or run:

ch workspace edit <workspace> --pr-status-badge true

Use false to turn it off. As with the check, the setting applies to that workspace only.

With the badge on, an agent adds the badge line to the description next to the task link when it opens the request. CodeHerder does not edit a description later.

When you turn the badge off, the image shows unknown at once. The agent removes the line the next time it edits the description.

Show or reset a task’s badge link

ch task badge <taskId>
ch task badge <taskId> --reset

The first command shows whether the workspace turned the badge on, and the image link. The second makes a new link. The old link then shows unknown. You need write access to the task. Reset the link if you shared it with someone by mistake.

Anyone who has the image link can see the badge. It shows only the fixed words above.

On a self-hosted server

GitHub loads the image through its own image proxy. That proxy must reach the /b/ path of your server from the public internet, or the image does not load. The status check does not need this, because your server sends it out to the git host. See Self-hosted deployment.

Troubleshooting

• No check on GitHub. The installation has neither Checks nor Commit statuses write permission, or an owner has not accepted the new permissions. Fix the App as described in Connecting the GitHub App.
• The check looks like a commit status, not a check run. The installation has Commit statuses but not Checks. Add Checks: Read and write.
• No check on GitLab. Check that the workspace GitLab token has the api scope.
• The merge stage waits on GitHub. CodeHerder is a required check. Remove it from the required checks.
• The badge image is broken on a self-hosted server. The /b/ path is not public. See On a self-hosted server.