github-action/guides/upgrading.md

Upgrading to a new version of the shared workflows

How a software engineer adopts a new release of the shared workflows safely: read the changelog, try the update in one place, and go back if it fails. The version rules are those of the release process: one version for the whole repository, tags vMAJOR.MINOR.PATCH and a moving major tag vMAJOR.

Which version you follow

In your uses: line	You receive	When to use it
@v1.2.0	nothing new, ever	a pipeline that must not change
@v1	compatible releases only (minor and patch)	the default for a project
@main	everything, unreleased	never; only for this repository's own tests

A breaking release gets a new major version (v2), so a pipeline on @v1 never receives it until you change the line yourself.

The quality-checks workflow fetches its script at its input tools-ref, which defaults to v1. To pin it completely, call it at an exact tag and set tools-ref to the same tag; otherwise the script follows the major tag.

The two scoped workflows (Sync GitHub mirror metadata and Publish wiki) are delivered by the instance and are not in your uses: lines; you cannot pin them, but they fetch their scripts at the major tag.

Reading a changelog entry

Open CHANGELOG.md of TirSystem/github-action, or the release page of the tag. An entry has up to four groups:

Group	What it means for you
Breaking	You must act: a name, an input, a secret or a default changed. A release with this group has a new major version
Added	Nothing to do; a new optional input, workflow or capability
Changed	Nothing to do; no visible effect for existing callers
Fixed	Nothing to do; a fix you receive on @v1

An entry that changes credentials, tokens or permissions says so; check your secrets before you upgrade.

Trying an update

1. Change the version in one repository, on a branch:

   jobs:
     quality:
       uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
   

2. Open a pull request and read the run. A failing check shows the tool, the file and the message (see the guide for reading quality-check results).
3. For a breaking release, follow the upgrade notes of the changelog entry, then repeat.
4. When the pull request is green, make the same change in the other repositories.

Going back

1. Change the line back to the previous exact tag, for example @v1.2.0, and merge it. Exact tags are never deleted or moved, so this always works.
2. Tell the maintainers which release failed and what you saw, so that the major tag can be moved back and a fix released.

When something is unclear

Symptom	Likely cause	Fix
The run says the workflow cannot be found	The tag does not exist, or the path is wrong	Check the tag on the release page and the path .gitea/workflows/quality-checks.yml
A green pipeline turned red after a release on @v1	A compatible release should not do this	Pin the previous exact tag and report it as a defect
An input is no longer accepted	A breaking release renamed it	Read the Breaking group of the entry