Skip to content

Release Process

Jump to bottom
Jeff Handley edited this page Jun 13, 2026 · 9 revisions

The following process describes the steps of releasing a new version of the Issue Labeler. The steps begin at the stage of the main branch containing what is desired to be marked as a new version of the workflows. The release process requires a few iterations capturing multiple commit SHA values to ensure each release is fully pinned to a consistent state through each layer of the architecture.

Create a new vX.Y.Z branch from main

The branch name should match the version to be released.

Run the 'Release' Action

  • Choose the vX.Y.Z branch created.
  • Click 'Run Workflow'

The release workflow publishes the predictor app image to GitHub's docker registry and updates the Issue Labeler's Actions that can be referenced by other repositories to encode the image's SHA. Those updated actions will be committed and pushed to the vX.Y.Z branch.

Important

The commit produced by the Release action lands on the vX.Y.Z branch, advancing its HEAD. The SHA of that commit — advertised in every uses: line of the release body and pointed to by the vX.Y.Z-release tag — is what consumers must pin to in their uses: lines. After publishing, the branch HEAD may advance further with post-release maintenance commits (for example, repinning the in-repo workflow templates to the just-released SHA); the release-body SHA remains canonical. See "The release-body SHA, the release tag, and the branch HEAD" below for details.

Create a GitHub Release

First, navigate to the vX.Y.Z branch and capture the latest commit SHA. The 'Release' process above will have added a commit to that branch for pinning the Docker Container Image's reference. That commit must be used for consumers to reference the new version of Issue Labeler.

The latest commit on the vX.Y.Z branch is shown as a placeholder below as {vX.Y.Z-commit-sha}.

Note the commit SHA is different from the SHA256 digest of the predictor app's Docker Container Image.

Using GitHub's Releases feature, draft a new release and choose/enter the following:

  • Create a new tag called vX.Y.Z-release
  • Choose the vX.Y.Z branch as the Target
  • Enter a title in the form of vX.Y.Z - {Title}
  • In the description, provide the following information to inform consumers how to reference the Issue Labeler's actions by pinning to the commit sha for this new version.
## Referencing vX.Y.Z

To reference `dotnet/issue-labeler` vX.Y.Z actions, workflows should pin to the SHA associated with the release as follows:

* `uses: dotnet/issue-labeler/download@{vX.Y.Z-commit-sha} # vX.Y.Z`
* `uses: dotnet/issue-labeler/train@{vX.Y.Z-commit-sha} # vX.Y.Z`
* `uses: dotnet/issue-labeler/test@{vX.Y.Z-commit-sha} # vX.Y.Z`
* `uses: dotnet/issue-labeler/promote@{vX.Y.Z-commit-sha} # vX.Y.Z`
* `uses: dotnet/issue-labeler/restore@{vX.Y.Z-commit-sha} # vX.Y.Z`
* `uses: dotnet/issue-labeler/predict@{vX.Y.Z-commit-sha} # vX.Y.Z`

Validate SHA consistency before publishing

Before publishing the release (or before merging any post-release patch commits to the vX.Y.Z branch), confirm the SHA pinned in every uses: line across the workflow templates on the vX.Y.Z branch matches the SHA shown in the release body. A scripted check is sufficient:

# Replace EXPECTED with the {vX.Y.Z-commit-sha} that the release body advertises
EXPECTED="<sha>"
cd <issue-labeler clone>
git checkout "$EXPECTED"

# Find any 'uses: dotnet/issue-labeler/<action>@<sha>' line whose SHA is not EXPECTED.
# If anything is printed, the templates and release body are out of sync.
grep -rIn 'dotnet/issue-labeler/[a-z]\+@' .github/workflows \
  | grep -v "$EXPECTED" \
  && echo "::error:: mismatched SHA above"

Past patch cycles have produced situations where the release body advertised one SHA while the workflow templates were pinned to a different SHA. This check catches that class of mistake before consumers copy the wrong reference.

The release-body SHA, the release tag, and the branch HEAD

Three related-but-distinct SHAs are associated with a release:

  • Release-body SHA — the SHA advertised in every uses: line of the GitHub release body. This is the canonical SHA consumers must pin to. It's also what every uses: line in this wiki references.
  • vX.Y.Z-release tag — a lightweight tag placed on the release-body SHA. The tag and the release-body SHA always match.
  • vX.Y.Z branch HEAD — at the moment of release this matches the release-body SHA. After publishing, the branch HEAD typically advances by at least one post-release maintenance commit (for example, a "Repin labeler workflows to latest vX.Y.Z SHA" commit that updates the in-repo workflow templates to reference the just-released SHA). Do not pin to the branch HEAD — pin to the release-body SHA.

For v2.1.0 these SHAs are concretely:

Ref SHA Pin?
Release body / v2.1.0-release tag 98f1d9b85686147ffdc155547cdd3469546c4e26 ✅ Yes
v2.1.0 branch HEAD dedab068d5b2fcc6f85fee4ea9e9be79c3f12449 ❌ No (post-release maintenance)

If a post-release patch is required (for example, to fix a workflow template), commit the change to the vX.Y.Z branch, move the vX.Y.Z-release tag and update the release body's uses: lines to reference the new SHA, re-run the SHA-consistency check above, and update the wiki's Onboarding snippets to match.

Clone this wiki locally