feat(ci): Attach the command reference to each release

The website only ever documents the newest release, so anyone staying on an
older version has nothing to read. Attach the generated markdown to the release
itself, which is also the copy to reach for offline.

The build job already generates those pages, so it packages them and passes them
on as a workflow artifact; the archive job is two steps, and nothing is built or
checked out twice. It stays a separate job because uploading needs a write token,
and the build job runs the Hugo theme — third-party template code should not
share a job with a token that can push to the repository.

Only tag_name and files are passed to action-gh-release, which leaves the body,
draft and prerelease fields of an existing release alone — release-please owns
the notes.

Author: khvn26

.github/workflows/docs.yml

@@ -1,8 +1,5 @@
 name: Docs
 
-# The published reference must describe a version people can install, so it is
-# built from release tags rather than from main. workflow_dispatch is here for
-# fixing the site itself (theme, landing page) without cutting a release.
 on:
   push:
     tags: ["v*"]
@@ -11,7 +8,7 @@ on:
 permissions:
   contents: read
 
-# One deployment at a time: GitHub Pages rejects concurrent deploys.
+# GitHub Pages rejects concurrent deploys.
 concurrency:
   group: pages
   cancel-in-progress: false
@@ -21,10 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      # configure-pages reads the site's base URL from the Pages API. It never
-      # creates the site: enablement defaults to false, so Pages has to be set
-      # to build from Actions by hand, and read is all this job needs.
-      pages: read
+      pages: read # read the site's base URL from the Pages API
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -43,12 +37,23 @@ jobs:
         run: go run ./cmd/docgen -out website/content
       - name: Build site
         working-directory: website
-        # configure-pages reports the correct base URL, which differs between a
-        # project site (/flagsmith-cli/) and a custom domain.
         run: hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
       - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: website/public
+      # The pages the site was just built from, for the archive job to attach.
+      - name: Package the reference
+        if: github.ref_type == 'tag'
+        run: |
+          cp -r website/content "$RUNNER_TEMP/reference"
+          tar -czf "$RUNNER_TEMP/flagsmith_${GITHUB_REF_NAME}_reference.tar.gz" -C "$RUNNER_TEMP" reference
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: github.ref_type == 'tag'
+        with:
+          name: reference
+          path: ${{ runner.temp }}/flagsmith_*_reference.tar.gz
+          if-no-files-found: error
+          retention-days: 1
 
   deploy:
     needs: build
@@ -62,3 +67,24 @@ jobs:
     steps:
       - uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
         id: deployment
+
+  # The site only ever documents the newest release, so attach a copy to the
+  # release itself for anyone staying on an older version. Kept out of the build
+  # job so the write token is never held by a job running the Hugo theme.
+  archive:
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # upload a release asset
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: reference
+      # Only tag_name and files are set: release-please owns the notes, and this
+      # action leaves body, draft and prerelease alone when they are not passed.
+      - uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        with:
+          tag_name: ${{ github.ref_name }}
+          files: flagsmith_*_reference.tar.gz
+          fail_on_unmatched_files: true

README.md

@@ -68,7 +68,7 @@ flagsmith flag list    # list the flags in the current environment
 
 Full reference for every command and flag: <https://flagsmith.github.io/flagsmith-cli/>.
 
-Reading works against any Flagsmith instance. Changing flags — `flag update`, `flag enable`/`disable`, `flag reorder`, `flag delete` — needs Flagsmith 2.263.0 or newer, self-hosted or SaaS.
+Reading works against any Flagsmith instance. Changing flags — `flag update`, `flag enable`/`disable`, `flag reorder`, `flag delete` — needs Flagsmith 2.263.0 or newer.
 
 - `flagsmith init` — bind the current directory to a project (writes `flagsmith.json`).
 - `flagsmith flag list` — list feature flags in the current environment.