GitHub Action release policy

ADR Guard publishes its GitHub Action from the same validated commit and release version used for the .NET Tool and container images.

The public GitHub Action release line starts at 1.0.0. This intentionally promotes the package baseline from the previous 0.1.x CLI releases so the first Marketplace-compatible release publishes both v1.0.0 and the consumer compatibility reference v1.

Published Action references

Each successful release publishes two Action references:

• vMAJOR.MINOR.PATCH — immutable. It is created once and must always point to the validated commit for that exact release.
• vMAJOR — movable compatibility reference. It advances to the newest successful release in that major line and never moves backwards during a rerun of an older release.

Examples:

# Reproducible Action source and runtime version.
uses: rodri-oliveira-dev/adr-guard@v1.2.3

# Receive compatible updates inside major version 1.
uses: rodri-oliveira-dev/adr-guard@v1

The Action never falls back to latest. An exact Action tag selects the matching exact GHCR image tag (@v1.2.3 -> :1.2.3). A moving major Action tag selects the matching moving major image tag (@v1 -> :1).

A commit SHA can also pin the Action source immutably, but the SHA does not encode a container version. Therefore SHA pinning must include an explicit exact version input:

uses: rodri-oliveira-dev/adr-guard@<commit-sha>
with:
  path: docs/adr
  command: check
  version: 1.2.3

Manual release trigger

Merging to main and completing CI no longer publishes a release. The Release workflow is triggered only through GitHub Actions workflow_dispatch.

To publish a release:

1. merge the intended changes into main;
2. wait for the normal CI on main to finish successfully;
3. open Actions → Release → Run workflow;
4. select the main branch, enter the required version with the exact SemVer of the intended release (normally the project’s VersionPrefix, without v), and start the workflow manually.

The required version input accepts stable MAJOR.MINOR.PATCH only: no leading zeroes, v prefix, prerelease, or build metadata. The requested version must be at least the project’s VersionPrefix and newer than any published or reserved version. To recover from an incomplete release, rerun the same version on the same commit, provided no newer version has been reserved or published. A version already owned by another commit, a version regression, or a second release version for the same commit is rejected before packaging. Release versions are not inferred from PR titles or commit messages.

The workflow verifies through the GitHub Actions API that the exact dispatched main commit already has a completed successful CI push run. If that CI is missing, still running, cancelled, or failed, the release stops before checkout/publication. It then re-runs restore, build, tests, packaging and smoke checks before any publication. Dispatches from branches other than main are rejected by the release job gate, so artifacts are bound to the explicitly dispatched main commit (github.sha). There is no automatic workflow_run trigger and no publication caused merely by a successful CI run.

Release ordering

The manually dispatched release workflow uses the selected main commit as the validated release commit and performs the release in this order:

1. build, test, and package the validated commit;
2. reserve the resolved SemVer with an internal release-reservation/vMAJOR.MINOR.PATCH tag tied to that validated commit;
3. publish the .NET Tool to NuGet.org;
4. publish the package to GitHub Packages;
5. publish the multi-platform container to GHCR and Docker Hub, including exact, minor, major, and latest image tags plus SBOM/provenance attestations;
6. verify the exact and major GHCR image references resolve to the OCI digest produced by that release;
7. smoke-test Action runtime resolution for both the exact and major references;
8. create or verify the immutable vMAJOR.MINOR.PATCH Git tag, update vMAJOR, and remove the completed reservation;
9. create the GitHub Release.

The Action tags are intentionally published after the container job succeeds. A failed container publication therefore cannot expose a new Action tag whose runtime artifact is missing. The internal reservation tag is not a supported Action reference and prevents a later commit from reusing a SemVer that may already have partially published artifacts.

Idempotency and conflicts

The exact SemVer tag is immutable. On a rerun:

• if vMAJOR.MINOR.PATCH already points to the validated commit, it is reused;
• if it points anywhere else, the release fails instead of repointing it;
• if vMAJOR already points to the same release, no update occurs;
• if vMAJOR points to an older release in the same major line, it advances;
• if a newer version has already been reserved or published, the manual workflow rejects retrying an older version; the Action-tag publication script independently prevents vMAJOR from moving backwards;
• if the existing major tag cannot be traced to an immutable release tag, the workflow refuses to overwrite it.

An existing GitHub Release is also treated as immutable. A missing package asset may be completed, but an existing asset is not overwritten with --clobber.

Verify a release

Given release v1.2.3, first confirm the Git tags:

git ls-remote --tags https://github.com/rodri-oliveira-dev/adr-guard.git \
  refs/tags/v1.2.3 refs/tags/v1

Both should resolve to the same commit immediately after the release. The exact tag must continue pointing to that commit forever; the major tag may advance on later v1.x.y releases.

Verify the runtime images:

docker buildx imagetools inspect ghcr.io/rodri-oliveira-dev/adr-guard:1.2.3
docker buildx imagetools inspect ghcr.io/rodri-oliveira-dev/adr-guard:1

Immediately after publication, both references should report the same top-level OCI digest. Later releases may move :1 while :1.2.3 remains immutable.

Finally, validate the Action from a consumer repository:

permissions:
  contents: read

steps:
  - uses: actions/checkout@<pinned-commit>
    with:
      persist-credentials: false

  - uses: rodri-oliveira-dev/adr-guard@v1.2.3
    with:
      path: docs/adr
      command: check

For supply-chain and runtime isolation details, see GitHub Action security model and container image and supply-chain guide.