UpdateVersionBranch

The UpdateVersionBranch job template proposes the update of a major-version branch. Consumers of an action or of a reusable workflow pin a major version (@v1, @r8), so every release has to move that branch. This template opens the pull-request that does it, titled like Updating r8 from v8.1.0, which is reviewed and merged like any other.

It is intended to run in the tag pipeline, beside PublishReleaseNotes.

Note

A major version that has no branch yet is created from the previous major, not from the main branch. A branch cut from the main branch is already identical to it, so there would be nothing to open a pull-request about. Branching from the previous major keeps the new branch behind the main branch, and the pull-request then carries exactly the changes between the last release of the previous major and the new one.

The highest existing lower major is used, so a jump from r3 to r9 works without an r8 in between.

Behavior

With app_id, create a token of that GitHub App; every following step works with it instead of the workflow’s own token.
Derive the branch name from prefix and either major or the major number of version. A major that isn’t a number is an error.
Create the branch if it is missing, from the highest existing lower major, or from main_branch when there is none.
Rewrite references to this repository - <owner>/<repository>[/<path>]@<ref> and the branch= parameter of a workflow-status badge - in the tracked *.yml, *.yaml and *.md files. Where a rewrite is needed, it becomes a commit on <update_branch_prefix><branch> and the pull-request is opened from there; where nothing needs rewriting, the pull-request is a plain merge of the main branch.
Open the pull-request, or retitle the one still open from the previous release. Its description is the body of the release version - the release notes; a release without notes gets a generated description and a warning.

The job does nothing when the version branch is already level with the main branch.

Note

Only self-references are rewritten. A reference to another repository, such as actions/checkout@v7, is a separate decision and is left alone, as is ./, which resolves to the calling ref by itself.

Prose about a reference is not rewritten either - the scan matches <owner>/<repository>@<ref>, not an English sentence mentioning a branch name.

Instantiation

The following instantiation example depicts the job beside a ReleasePage job in the same tag pipeline. Both are gated on is_release_tag from a Prepare job derived from job template PrepareJob.

jobs:
  Prepare:
    uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r8

  # Other pipeline jobs

  ReleasePage:
    uses: pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml@r8
    needs:
      - Prepare
    if: needs.Prepare.outputs.is_release_tag == 'true'
    with:
      tag: ${{ needs.Prepare.outputs.version }}
    secrets: inherit

  UpdateVersionBranch:
    uses: pyTooling/Actions/.github/workflows/UpdateVersionBranch.yml@r8
    needs:
      - Prepare
    if: needs.Prepare.outputs.is_release_tag == 'true'
    permissions:
      contents:      write   # required to create a version branch
      pull-requests: write   # required to open the pull-request
    with:
      version: ${{ needs.Prepare.outputs.version }}
      prefix:  'r'
      app_id:  ${{ vars.RELEASE_APP_ID }}
    secrets:
      app_private_key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image	no	string	`'ubuntu-26.04'`
version	yes	string	— — — —
prefix	no	string	`'v'`
major	no	string	`''`
main_branch	no	string	`'main'`
update_branch_prefix	no	string	`'update/'`
app_id	no	string	`''`

Goto secrets

Token Name	Required	Type	Default
app_private_key	no	string	— — — —

Goto output parameters

Parameter Name	Type	Description
branch	string	Name of the version branch.
branch-created	string	`'true'` if the branch was created by this run.
head	string	Branch the pull-request was opened from.
rewritten	string	`'true'` if references had to be rewritten.
pull-request	string	URL of the pull-request, empty if none was needed.

Input Parameters

ubuntu_image

Type:: string
Required:: no
Default Value:: 'ubuntu-26.04'
Possible Values:: See actions/runner-images - Available Images for available Ubuntu image versions.
Description:: Name of the Ubuntu image used to run this job.

version

Type:: string
Required:: yes
Default Value:: — — — —
Possible Values:: A version with a leading major number, optionally prefixed by v or r, e.g. v8.1.0, r8.1.0 or 8.1.0.
Description:: The released version, as tagged. Its major number selects the version branch: v1.2.3 with prefix r targets branch r1.
Usually PrepareJob’s version output parameter.

prefix

Type:: string
Required:: no
Default Value:: 'v'
Possible Values:: Usually 'v' or 'r'.
Description:: Prefix of the version branch name. It is independent of the version’s own prefix, so a repository tagging v8.1.0 while publishing r8 branches sets 'r' here.

major

Type:: string
Required:: no
Default Value:: ''
Possible Values:: A non-negative integer, or empty.
Description:: Major version number selecting the version branch. When empty, the major number of version is used.
Set it where the version branch doesn’t follow the released version’s major at all - GitHub: pyTooling/download-artifact tags v1.10.0 while publishing a v8 branch, so it passes major: '8'.

main_branch

Type:: string
Required:: no
Default Value:: 'main'
Possible Values:: Any branch name.
Description:: Branch the version branch is updated from - the branch releases are tagged on.

update_branch_prefix

Type:: string
Required:: no
Default Value:: 'update/'
Possible Values:: Any branch name prefix.
Description:: Prefix of the branch carrying the rewritten references. It is used only when a rewrite is needed, and is force-pushed on every release, so nothing should pin it.

app_id

Type:: string
Required:: no
Default Value:: ''
Possible Values:: The ID of a GitHub App, or empty.
Description:: ID of a GitHub App installed on the repository with write access to Contents, Workflows and Pull requests. Together with app_private_key, the job creates a token of that App (GitHub: actions/create-github-app-token) and uses it for all its steps.
The workflow’s own GITHUB_TOKEN can’t push a change to a file in .github/workflows/ - no permissions: key grants that - so a release changing a workflow file needs the App. When empty, the job uses GITHUB_TOKEN.
The App ID isn’t secret, so a repository variable is enough, e.g. ${{ vars.RELEASE_APP_ID }}.

Secrets

Without app_id, this job template needs no secrets. It then uses the automatic GITHUB_TOKEN, which needs contents: write and pull-requests: write granted by the calling job.

app_private_key

Type:: string
Required:: no
Default Value:: — — — —
Description:: Private key of the GitHub App named by app_id, as the PEM file’s full content, e.g. ${{ secrets.RELEASE_APP_PRIVATE_KEY }}. A secret can hold several lines, so the file is stored unchanged: gh secret set RELEASE_APP_PRIVATE_KEY < app.pem.

Outputs

branch

Type:: string
Description:: Name of the version branch, e.g. r8.

branch-created

Type:: string
Description:: 'true' if the version branch didn’t exist and was created by this run, 'false' otherwise.

head

Type:: string
Description:: Branch the pull-request was opened from: the main branch, or the update branch when references were rewritten.

rewritten

Type:: string
Description:: 'true' if references to this repository had to be rewritten for the version branch.

pull-request

Type:: string
Description:: URL of the created or updated pull-request. Empty when the version branch was already level with the main branch.

Optimizations

The reference rewrite is skipped entirely when no tracked file mentions this repository, in which case the pull-request is a plain merge and no update branch is pushed.