fix: Fix workflows with release tagging and semver support (#8)

Author: AndyRae

.github/workflows/semantic-release.yml

@@ -12,6 +12,9 @@ on:
       release-created:
         description: 'Whether semantic-release created a new release/tag'
         value: ${{ jobs.release.outputs.release-created }}
+      release-tag:
+        description: 'The tag created by semantic-release (empty if no release was created)'
+        value: ${{ jobs.release.outputs.release-tag }}
 
 permissions:
   contents: write
@@ -21,16 +24,21 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
+    # Prevent concurrent releases from the same repository. A queued run will wait
+    # rather than being cancelled, ensuring no release commit is ever skipped.
     concurrency:
       group: semantic-release-${{ github.repository }}
       cancel-in-progress: false
     outputs:
       release-created: ${{ steps.release-check.outputs.release-created }}
+      release-tag: ${{ steps.release-check.outputs.release-tag }}
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
+          # Full history is required — semantic-release reads all commits since the last
+          # tag to determine the next version and generate the changelog.
           fetch-depth: 0
 
       - name: Set up Node.js
@@ -47,6 +55,8 @@ jobs:
             @semantic-release/changelog \
             @semantic-release/github
 
+      # Snapshot the current tags before running semantic-release so we can diff
+      # afterwards to find exactly which tag (if any) was newly created.
       - name: Capture tags before release
         run: |
           git fetch --tags --force
@@ -62,20 +72,39 @@ jobs:
           git fetch --tags --force
           git tag -l | sort > /tmp/tags-after.txt
 
+      # semantic-release does not reliably expose whether it created a release via exit
+      # codes or stdout — behaviour varies across plugin configurations. Instead we diff
+      # the tag snapshots taken before and after, then check whether any new tag points
+      # at HEAD. This approach works regardless of the release.config.js in the caller repo.
       - name: Determine whether release was created
         id: release-check
         run: |
           head_sha=$(git rev-parse HEAD)
+
+          # comm -13 outputs lines present in the second file but not the first,
+          # i.e. tags that did not exist before semantic-release ran.
           new_tags=$(comm -13 /tmp/tags-before.txt /tmp/tags-after.txt)
           release_created=false
+          release_tag=""
+
+          # Short-circuit if no new tags were created at all.
+          if [ -z "$new_tags" ]; then
+            echo "release-created=false" >> "$GITHUB_OUTPUT"
+            echo "release-tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
 
           while IFS= read -r tag; do
+            # Lightweight tags point directly to a commit; annotated tags point to a tag
+            # object which in turn points to a commit. The '^{}' suffix dereferences an
+            # annotated tag to its underlying commit SHA so both cases are handled uniformly.
             tag_sha=$(git rev-parse "${tag}^{}" 2>/dev/null || git rev-parse "$tag")
             if [ "$tag_sha" = "$head_sha" ]; then
               release_created=true
+              release_tag="$tag"
               break
             fi
           done <<< "$new_tags"
 
           echo "release-created=$release_created" >> "$GITHUB_OUTPUT"
-
+          echo "release-tag=$release_tag" >> "$GITHUB_OUTPUT"

.github/workflows/semver-container.yml

@@ -12,6 +12,10 @@ on:
         required: false
         default: 'ghcr.io'
         type: string
+      tag:
+        description: 'The release tag to derive semver from (e.g. 1.2.3 or v1.2.3)'
+        required: true
+        type: string
 
 env:
   image-name: ${{ inputs.image-name }}
@@ -22,47 +26,74 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       packages: write # container images
-      contents: write # releases
     steps:
-      - name: Check out the repo
-        uses: actions/checkout@v4
-
-      # some docker actions need all lowercase
+      # docker/metadata-action and akhilerm/tag-push-action require lowercase registry paths.
+      # GITHUB_REPOSITORY_OWNER can contain uppercase letters (e.g. "Health-Informatics-UoN"),
+      # so we normalise it here and store it in GITHUB_ENV for all subsequent steps.
       - name: downcase repo-owner
         run: |
           echo "REPO_OWNER_LOWER=${GITHUB_REPOSITORY_OWNER,,}" >>${GITHUB_ENV}
 
       - name: Parse version from tag
         id: version
-        uses: release-kit/semver@97491c46500b6e758ced599794164a234b8aa08c # v2.0.7
+        run: |
+          # The tag input may optionally be prefixed with 'v' (e.g. v1.2.3).
+          # Strip it so all subsequent steps work with a bare semver string.
+          version="${{ inputs.tag }}"
+          version="${version#v}"
+
+          # Extract the major and minor components for floating tags (e.g. '1' and '1.2').
+          # Floating tags let consumers pin to a major or minor version without knowing
+          # the exact patch, following standard container image tagging conventions.
+          major=$(echo "$version" | cut -d. -f1)
+          minor=$(echo "$version" | cut -d. -f2)
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "major=$major" >> "$GITHUB_OUTPUT"
+          echo "major-minor=$major.$minor" >> "$GITHUB_OUTPUT"
+
+          # A hyphen in the version string indicates a pre-release (e.g. 1.0.0-beta.1).
+          # Floating major/minor tags must NOT be applied to pre-releases — those tags
+          # should always point at the latest stable release, not a pre-release build.
+          if [[ "$version" == *-* ]]; then
+            echo "is-prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is-prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
 
-      # check image exists for commit
-      - uses: tyriis/docker-image-tag-exists@71a750a41aa78e4efb0842f538140c5df5b8166f # v2.1.0
+      # Verify that the edge image built from this commit SHA actually exists in the registry
+      # before attempting to retag it. Fails fast rather than producing a misleading error
+      # from the tag-push step if the publish-container workflow hasn't run yet.
+      - name: Check image exists for commit
+        uses: tyriis/docker-image-tag-exists@71a750a41aa78e4efb0842f538140c5df5b8166f # v2.1.0
         with:
           registry: ${{ env.registry }}
           repository: ${{ env.REPO_OWNER_LOWER }}/${{ env.image-name }}
           tag: ${{ github.sha }}
 
-      # standard login to the container registry
       - name: Docker Login
         uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
         with:
           registry: ${{ env.registry }}
           username: ${{github.actor}}
           password: ${{secrets.GITHUB_TOKEN}}
 
-      # We still use the metadata action to help build out our tags from the Workflow Run
+      # Build the list of tags to apply. We use type=raw because the version comes from
+      # the 'tag' input rather than from GITHUB_REF — this workflow is triggered via
+      # workflow_call on a branch push, so GITHUB_REF is a branch ref, not a tag ref.
+      # The major and minor floating tags are gated on is-prerelease so they are only
+      # moved forward for stable releases.
       - name: Docker Metadata action
         id: meta
         uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 # v5.7.0
         with:
           images: ${{ env.registry }}/${{ env.REPO_OWNER_LOWER }}/${{ env.image-name }}
-          tags: | # new tags only
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}
-            type=semver,pattern={{major}}.{{minor}}
+          tags: |
+            type=raw,value=${{ steps.version.outputs.version }}
+            type=raw,value=${{ steps.version.outputs.major }},enable=${{ steps.version.outputs.is-prerelease == 'false' }}
+            type=raw,value=${{ steps.version.outputs.major-minor }},enable=${{ steps.version.outputs.is-prerelease == 'false' }}
 
-      # apply the new tags to the existing images
+      # Rather than rebuilding the image, we retag the existing edge image (tagged with
+      # the commit SHA by publish-container) with the semver tags computed above.
       - name: Push updated image tags
         uses: akhilerm/tag-push-action@f35ff2cb99d407368b5c727adbcc14a2ed81d509 # v2.2.0
         with:

docs/semantic-release.md

@@ -10,11 +10,12 @@ Reusable workflow that runs [semantic-release](https://github.com/semantic-relea
 
 ## Outputs
 
-| Output            | Description                                              |
-|-------------------|----------------------------------------------------------|
-| `release-created` | `'true'` if a new release was created, `'false'` if not. |
+| Output            | Description                                                              |
+|-------------------|--------------------------------------------------------------------------|
+| `release-created` | `'true'` if a new release was created, `'false'` if not.                 |
+| `release-tag`     | The tag created by semantic-release (e.g. `1.2.3`). Empty string if no release was created. |
 
-Use this to conditionally run downstream jobs (e.g. re-tag a container, publish to PyPI) only when a release actually happened:
+Use these to conditionally run downstream jobs (e.g. re-tag a container, publish to PyPI) only when a release actually happened:
 
 ```yaml
 jobs:
@@ -25,7 +26,11 @@ jobs:
   publish:
     needs: release
     if: needs.release.outputs.release-created == 'true'
-    ...
+    uses: health-informatics-uon/workflows/.github/workflows/semver-container.yml@main
+    with:
+      image-name: my-app
+      tag: ${{ needs.release.outputs.release-tag }}
+    secrets: inherit
 ```
 
 > **Note:** If the workflow itself errors, `release-created` will be an empty string rather than `'false'`. Always use `== 'true'` rather than `!= 'false'` in conditions.

docs/semver-container.md

@@ -2,41 +2,46 @@
 
 Reusable workflow that:
 
-- tags an existing container image with semver tags (`x.y.z`, `x`, `x.y`) based on the git tag
+- tags an existing container image with semver tags (`x.y.z`, `x`, `x.y`) based on a provided release tag
 - verifies that a corresponding container image (tagged with the commit SHA) already exists
 
-Use this when you already have an \"edge\" or commit-SHA container image (for example from the `publish-container` workflow) and you want to promote it to a semver release.
+Use this when you already have an "edge" or commit-SHA container image (for example from the `publish-container` workflow) and you want to promote it to a semver release.
 
-## Inputs
+> **Note:** The `x` and `x.y` floating tags are only applied for stable releases. Pre-release versions (e.g. `1.0.0-beta.1`) receive only the full version tag.
 
-| Input               | Required | Default                            | Description                                                      |
-|---------------------|----------|------------------------------------|------------------------------------------------------------------|
-| `image-name`        | Yes      | —                                  | Image name, e.g. `my-app` or `services/api`.                     |
-| `registry`          | No       | `'ghcr.io'`                        | Registry host.                                                   |
-| `release-name-prefix` | No     | `''`                               | String prefixed to the Release title (e.g. project name + space).|
+## Inputs
 
+| Input        | Required | Default     | Description                                          |
+|--------------|----------|-------------|------------------------------------------------------|
+| `image-name` | Yes      | —           | Image name, e.g. `my-app` or `services/api`.         |
+| `registry`   | No       | `'ghcr.io'` | Registry host.                                       |
+| `tag`        | Yes      | —           | The release tag to derive semver from (e.g. `1.2.3` or `v1.2.3`). Typically passed from the `release-tag` output of the `semantic-release` workflow. |
 
 ## Secrets
 
-- `GITHUB_TOKEN` — Pass with `secrets: inherit` so the workflow can read tags, create releases, and push tags in the container registry.
+- `GITHUB_TOKEN` — Pass with `secrets: inherit` so the workflow can push tags in the container registry.
 
 ## Usage
 
-This workflow is designed to as part of a release process.
+This workflow is designed to run as part of a release process, chained after `semantic-release`:
 
 ```yaml
 jobs:
+  release:
+    uses: health-informatics-uon/workflows/.github/workflows/semantic-release.yml@main
+    secrets: inherit
+
   semver-container:
+    needs: release
+    if: needs.release.outputs.release-created == 'true'
     uses: health-informatics-uon/workflows/.github/workflows/semver-container.yml@main
     with:
       image-name: my-service
-      registry: ghcr.io
-      release-name-prefix: 'My Service '
+      tag: ${{ needs.release.outputs.release-tag }}
     secrets: inherit
 ```
 
 This will:
 
 - check that an image `ghcr.io/<owner>/my-service:<sha>` exists
-- push additional tags like `1.2.3`, `1`, and `1.2` to that image
-
+- push additional tags like `1.2.3`, `1`, and `1.2` to that image (or just `1.2.3` for pre-releases)