Add floating version tag actions and the release workflow that uses them

.github/actions/move-git-tags/README.md

@@ -0,0 +1,135 @@
+# move-git-tags
+
+Creates or moves the named git tags so that they point at a commit. A tag that does not exist is
+created, one that does is repointed.
+
+It knows nothing about versions. [resolve-floating-tags](../resolve-floating-tags/) decides which
+floating version tags a release should own and this action writes them:
+
+```yaml
+- name: Resolve the floating tags for this release
+  id: floating
+  uses: stellarwp/plugin-toolbox/.github/actions/resolve-floating-tags@v1
+  with:
+    tag: ${{ github.event.release.tag_name }}
+
+- name: Move them onto the released commit
+  uses: stellarwp/plugin-toolbox/.github/actions/move-git-tags@v1
+  with:
+    tags: ${{ steps.floating.outputs.tags }}
+```
+
+Any tag name works, so it also moves a `stable` or `latest` pointer, or a release tag that has to be
+repointed at a build commit. `sha` defaults to the commit the run is for, so most callers pass only
+the names:
+
+```yaml
+- uses: stellarwp/plugin-toolbox/.github/actions/move-git-tags@v1
+  with:
+    tags: stable
+```
+
+## Inputs
+
+| Input | Required | Default | What it does |
+|---|---|---|---|
+| `tags` | yes | | Tag names to create or move, separated by spaces or newlines, e.g. `v1 v1.2` |
+| `sha` | no | the commit the run is for | The commit the tags should point at |
+| `repository` | no | current repo | The `<owner>/<repo>` to write the tags in |
+| `token` | no | `github.token` | Writes the tag refs. See [Permissions](#permissions) |
+
+## Outputs
+
+| Output | Example | What it is |
+|---|---|---|
+| `created` | `v1.2` | Tags that did not exist and were created |
+| `moved` | `v1` | Tags that already existed and were repointed |
+
+## An empty tag list is not an error
+
+`tags: ''` moves nothing and succeeds, so a caller feeding it another step's output needs no `if:`
+of its own. resolve-floating-tags returns an empty `tags` whenever the release should own no
+floating tags, and the job stays green.
+
+## Permissions
+
+The job needs `contents: write`, which is not the default when a workflow sets
+`permissions: contents: read` at the top:
+
+```yaml
+jobs:
+  move-floating-tags:
+    permissions:
+      contents: write
+```
+
+`github.token` is the token of the workflow that runs this action, scoped to that repository, so a
+repo calling this action writes its own tags with its own token and needs no secret.
+
+Pass a PAT or app token as `token` instead in either of two cases. One is a ruleset that protects the
+tags in a way `github.token` cannot satisfy; a tag protection rule that blocks the default token makes
+the API call fail rather than silently skip.
+
+The other is a repo whose own workflows have to react to the tag. GitHub creates no workflow run for
+an event made with `GITHUB_TOKEN`, apart from `workflow_dispatch` and `repository_dispatch`, so a
+workflow listening on `push:` for `tags:` will not see a tag this action moved.
+
+## Why the API and not git push
+
+Writing the refs through the API rather than `git push --force` means the tag name never disappears
+for a moment, which is what keeps a GitHub Release attached to it. It also means the job needs no
+checkout of the repo to move a tag.
+
+Each tag is read with `git.getRef` before being written, instead of trying `git.updateRef` and
+creating the tag when that fails. An update also fails for a token without permission or a protected
+tag, and a fallback would report those as a successful creation. Only a 404 is read as "does not
+exist"; any other status fails the job.
+
+`getRef` is the single-ref endpoint on purpose. `listMatchingRefs` matches by prefix, so it answers
+for `tags/v1` whenever a `v1.0.0` tag exists even when there is no `v1` to update:
+
+```console
+$ gh api repos/stellarwp/changelogger/git/refs/tags/0.1 --jq 'map(.ref)'
+["refs/tags/0.1.0","refs/tags/0.10.0"]
+
+$ gh api repos/stellarwp/changelogger/git/ref/tags/0.1
+gh: Not Found (HTTP 404)
+```
+
+The two calls also spell the ref differently: `getRef` and `updateRef` take `tags/v1`, while
+`createRef` takes the full `refs/tags/v1`.
+
+## Tag names
+
+Pass tag names, not refs. `refs/tags/v1` is refused, because writing it would create a tag named
+`refs/tags/v1`.
+
+A name has to start with a letter or digit and hold only letters, digits, `.`, `_`, `-` and `/`.
+`..` is refused as well. Each name goes into an API path, so anything else stops the job instead of
+being sent.
+
+## Lightweight tags only
+
+The refs are written straight to a commit, so these are lightweight tags with no tagger, date or
+message of their own. A floating tag is repointed every time a release claims it, so an annotated tag
+object would be replaced each time.
+
+A release tag that has to be annotated or signed is created by whoever cuts the release, not here.
+
+## How it runs
+
+The logic is in `move.js`, run by [actions/github-script](https://github.com/actions/github-script),
+which supplies the Node runtime and an Octokit already authenticated with `token`. There is no
+dependency to install and no bundle to build: the file in the repository is the file that runs, so a
+change to it is reviewable as a diff.
+
+The script is loaded by path rather than inlined in the manifest, because github-script's `require`
+resolves against the workspace of the repository being built, not this action's directory. The path
+comes from `${{ github.action_path }}`.
+
+Inputs reach the script through `process.env`, never by being interpolated into it, so a tag name is
+data and cannot become part of the program.
+
+`tests/actions/move-git-tags/move.test.js` covers the rules above. It drives the
+real Octokit with the network replaced, so the assertions are the requests this action would
+send. Run `npm install` once, then `node --test`.

.github/actions/move-git-tags/action.yml

@@ -0,0 +1,63 @@
+# Creates or moves git tags through the GitHub API. Knows nothing about versions: pair it with
+# .github/actions/resolve-floating-tags to move floating version tags, or hand it any tag name.
+#
+# The work lives in move.js. actions/github-script runs it with a pre-authenticated Octokit, so
+# there is no dependency to install and nothing to build: the file in the repository is the file
+# that runs.
+name: Move git tags
+description: Creates or moves the named git tags so that they point at a commit
+
+inputs:
+  tags:
+    description: >-
+      The tags to create or move, separated by spaces or newlines, e.g. `v1 v1.2`. An empty value
+      moves nothing and succeeds, so a caller passing another step's output needs no `if:` of its
+      own. Names are tag names, not refs: pass `v1`, not `refs/tags/v1`.
+    required: true
+  sha:
+    description: >-
+      The commit the tags should point at. Defaults to the commit the workflow is running for, which
+      on a `release` event is the commit the release tag names.
+    required: false
+    default: ''
+  repository:
+    description: 'The `<owner>/<repo>` to write the tags in. Defaults to the current repository.'
+    required: false
+    default: ''
+  token:
+    description: >-
+      Token used to write the tag refs. It needs `contents: write` on the repository, so the job
+      needs that permission too. Pass a PAT or app token instead when a ruleset protects the tags in
+      a way the default token cannot satisfy.
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  created:
+    description: 'The tags that did not exist and were created, space separated.'
+    value: ${{ steps.move.outputs.created }}
+  moved:
+    description: 'The tags that already existed and were repointed, space separated.'
+    value: ${{ steps.move.outputs.moved }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Create or move the tags
+      id: move
+      uses: actions/github-script@v9
+      env:
+        # github-script's require() resolves against the workspace of the repository being built,
+        # not this action's directory, so the path has to be passed in. github.action_path is the
+        # documented expression for it.
+        ACTION_PATH: ${{ github.action_path }}
+        # Read from process.env rather than interpolated into the script, so a tag name is data and
+        # never part of the program.
+        INPUT_TAGS: ${{ inputs.tags }}
+        INPUT_SHA: ${{ inputs.sha }}
+        INPUT_REPOSITORY: ${{ inputs.repository }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const { run } = require(`${process.env.ACTION_PATH}/move.js`)
+          await run({ github, core, env: process.env })

.github/actions/move-git-tags/move.js

@@ -0,0 +1,131 @@
+'use strict'
+
+/**
+ * Creates or moves git tags so that they point at a commit.
+ *
+ * parseTagNames is pure and holds the validation. moveTags takes an Octokit and does the writing,
+ * so a test can pass a stand-in and assert the calls.
+ */
+
+/** A plain tag name: no spaces, no leading dash or dot, nothing that could reshape a request. */
+const PLAIN_TAG_NAME = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/
+
+/**
+ * Splits the `tags` input and checks every name.
+ *
+ * @param {string} tags Tag names separated by spaces or newlines.
+ *
+ * @throws {Error} When a name is not a plain tag name.
+ *
+ * @returns {string[]} The names, in the order given.
+ */
+function parseTagNames(tags) {
+  const names = String(tags ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+
+  for (const name of names) {
+    // A full ref would otherwise be written as a tag literally named refs/tags/v1.
+    if (name.startsWith('refs/')) {
+      throw new Error(`Refusing to write '${name}': pass the tag name, e.g. '${name.split('/').pop()}'.`)
+    }
+
+    if (!PLAIN_TAG_NAME.test(name) || name.includes('..')) {
+      throw new Error(`Refusing to write '${name}': it is not a plain tag name.`)
+    }
+  }
+
+  return names
+}
+
+/**
+ * Points each tag at a commit, creating the ones that do not exist.
+ *
+ * The ref is read first rather than trying an update and creating on failure. An update also fails
+ * for a token without permission or a protected tag, and treating that as "does not exist yet"
+ * would report a refused write as a successful creation. getRef is the single-ref endpoint, which
+ * answers 404 for a missing ref; the matching-refs endpoint matches by prefix instead, and would
+ * answer for `tags/v1` whenever a v1.0.0 tag exists.
+ *
+ * The refs are written through the API rather than by pushing, so a tag name never disappears for a
+ * moment, which is what keeps a GitHub Release attached to it.
+ *
+ * @param {object}   github An Octokit, as actions/github-script supplies it.
+ * @param {object}   core   The @actions/core toolkit, for the log.
+ * @param {string}   owner  The repository owner.
+ * @param {string}   repo   The repository name.
+ * @param {string[]} names  The tag names to point at `sha`, already validated.
+ * @param {string}   sha    The commit the tags should point at.
+ *
+ * @throws {Error} When a write fails, or a read fails with anything but a 404.
+ *
+ * @returns {Promise<{created: string[], moved: string[]}>} Which names were created, and which
+ *                                                          already existed and were repointed.
+ */
+async function moveTags({ github, core, owner, repo, names, sha }) {
+  const created = []
+  const moved = []
+
+  for (const name of names) {
+    let exists = true
+
+    try {
+      // getRef takes the ref without its `refs/` prefix; createRef takes the full ref below.
+      await github.rest.git.getRef({ owner, repo, ref: `tags/${name}` })
+    } catch (error) {
+      if (error.status !== 404) {
+        throw error
+      }
+
+      exists = false
+    }
+
+    if (exists) {
+      await github.rest.git.updateRef({ owner, repo, ref: `tags/${name}`, sha, force: true })
+      core.info(`Moved ${name} to ${sha}.`)
+      moved.push(name)
+    } else {
+      await github.rest.git.createRef({ owner, repo, ref: `refs/tags/${name}`, sha })
+      core.info(`Created ${name} at ${sha}.`)
+      created.push(name)
+    }
+  }
+
+  return { created, moved }
+}
+
+/**
+ * Moves the tags named by the inputs and writes the action's outputs.
+ *
+ * @param {object} github An Octokit, as actions/github-script supplies it.
+ * @param {object} core   The @actions/core toolkit, for the log and the outputs.
+ * @param {object} env    The environment the action manifest put its inputs in.
+ *
+ * @throws {Error} When a tag name is not a plain tag name, or a write fails.
+ *
+ * @returns {Promise<void>} Resolves once every tag has been written and the outputs are set.
+ */
+async function run({ github, core, env }) {
+  const repository = env.INPUT_REPOSITORY || env.GITHUB_REPOSITORY
+  const [owner, repo] = repository.split('/')
+  const sha = env.INPUT_SHA || env.GITHUB_SHA
+  const names = parseTagNames(env.INPUT_TAGS)
+
+  // An empty list succeeds, so a caller feeding this another step's output needs no `if:` of
+  // its own.
+  if (names.length === 0) {
+    core.info('No tags to move.')
+    core.setOutput('created', '')
+    core.setOutput('moved', '')
+
+    return
+  }
+
+  const { created, moved } = await moveTags({ github, core, owner, repo, names, sha })
+
+  core.setOutput('created', created.join(' '))
+  core.setOutput('moved', moved.join(' '))
+}
+
+module.exports = { run, moveTags, parseTagNames, PLAIN_TAG_NAME }