Add docs

Author: AndyRae

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)