Release actions
Let a stage that runs after the merge dispatch repo workflows and push a release tag. It is off by default and never pushes a branch.
A release or verify stage often has to start a deploy workflow and push a version tag. By default it cannot. A read-only stage has no push right. Even a stage that can commit has no token that can run a workflow.
A repo can opt in with the Release actions setting. With it on, a stage that runs after the task’s merge may dispatch workflows and push a tag. The setting is off by default.
What a stage can do
On a repo that allows release actions, a stage after the merge can:
- GitHub: dispatch a workflow (
gh workflow run <workflow> --ref <default-branch>). Re-run a workflow run or its failed jobs (gh run rerun). - GitLab: run a pipeline (
glab ci run -b <default-branch>). Retry a pipeline or a job. - Both: create a tag (
git tag <tag> <sha>, thengit push origin <tag>).
A tag must be a lightweight tag of a commit that is already on the default branch. Do not use git tag -a or -s. The relay checks the commit with the host before it lets the push go.
A workflow or pipeline must run on the default branch or on a tag. For a GitHub dispatch, name a tag as refs/tags/<tag>. A short tag name is refused because a branch can have the same name. The relay also checks where a tag points. A tag whose commit is not on the default branch is refused, even if the tag existed before the merge.
A dispatch or pipeline carries no inputs or variables. A GitHub dispatch takes only ref, so a workflow with required inputs cannot be dispatched. A GitLab pipeline takes only ref. A re-run, retry or play takes no parameters, so enable_debug_logging and job_variables_attributes are refused. A GitHub release call takes no query string. Put a value in the project’s CI settings or in the workflow file instead. Send a GitLab body as application/json or as a form. The relay refuses any other content type, and a key that appears twice.
A re-run, retry or play must name a run, pipeline or job on the default branch or on a tag, at a commit that is on the default branch. A run on another branch or a pull request is refused.
What it can never do
The token is narrow. The git relay on the device checks every call before it goes to the host. The relay refuses:
- A branch push. This covers a new branch, an update, a delete and a force push. A push that holds a branch and a tag is refused as a whole.
- A change to an existing tag. A tag push must create a new tag.
- A new commit. A push that carries objects is refused. This covers an annotated tag. A tag may name only a commit that is on the default branch.
- A change to a workflow file. The token has no Workflows permission.
- Any other API call. Branch protection, the contents API, merges, secrets and settings stay refused.
- A call before the merge. See the rules below.
When it applies
All of these must be true when the stage starts:
- The repo allows release actions.
- The repo is on the workspace list as read and write.
- The stage sits after the merge stage in the task’s workflow.
The server checks the same rules again each time the device asks for the token. It also needs a merge request of the task, on that repo, that the host shows as merged. A stage before the merge never gets the token, even with the setting on. A task that goes back to code loses the right at the next stage start.
Turn it on
Only a workspace owner or admin can change it. It must be a person’s account. An agent cannot change it.
ch repo edit <name|id> --allow-release-actions
ch repo edit <name|id> --deny-release-actions
On the web app, open the repo’s page and use the Release actions row. ch repo show prints the setting in a release actions row. The change applies from the next stage start. Each change adds a release actions changed entry to the repo’s activity feed.
Set up the GitHub App
The App needs Actions: Read and write on the installation. It also needs Contents: Read and write. See Connecting the GitHub App. An owner of each organization must accept the new permission on each installation.
If the installation lacks Actions write, the server refuses the token. The relay then refuses the release action. The error names the missing permission. It does not fall back to a wider token.
GitLab notes
The workspace needs a GitLab connection that can mint project tokens. See Server-minted tokens. The token acts as a Developer. A project can protect its tags so that only a Maintainer may create them. If so, the tag push fails at GitLab. CodeHerder does not raise the role. Change the protected tag rule, or push the tag by hand.
The audit trail
Each admitted workflow dispatch, re-run, pipeline run, pipeline retry and tag push adds a task.release_action event to the task. The event names the kind, the repo, the workflow or the tag, the ref and the commit. You can subscribe to it. If the server cannot record events, the relay refuses the action.
The risk
A workflow runs with the repo’s secrets. A tag can start a release workflow. Turn the setting on only for a repo whose workflows you trust. The relay admits only the default branch or a tag. A tag can name only a commit that is on the default branch. So a stage cannot run a workflow from code that nobody reviewed.
The relay is the only narrowing. A GitHub App token cannot be limited to tags. The relay runs only for a stage that uses the Docker executor. A stage on another executor gets no release actions.
If a call is refused
A refusal names release actions in its message. Check these points in order:
- The repo setting is on, and the stage started after you turned it on.
- The task has a merged merge request on that repo.
ch task merge-requests list <task>shows it. - The GitHub installation grants Actions write.
- The ref is the default branch or
refs/tags/<tag>. - The tag is lightweight, and its commit is on the default branch.
- The call carries no inputs or variables.
- A re-run, retry or play names a run, pipeline or job on the default branch or a tag.
If none of these fixes it, say so in the hand-off. Do not look for another way to push.
Last updated