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 hands them to the archive job
as an artifact and nothing is built or checked out twice. It uploads that
artifact on every run, not only on tags, so a dispatched run leaves the pages
somewhere they can be inspected. Archiving happens on the far side of the
handover because an artifact is not a release asset and its zip needs a token to
fetch, so the tarball has to be made somewhere; doing it there also avoids
wrapping a tarball inside the artifact's own zip.

Attaching stays a separate job because it 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,17 @@ 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.
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: reference
+          path: website/content
+          if-no-files-found: error
+          retention-days: 1
 
   deploy:
     needs: build
@@ -62,3 +61,23 @@ 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.
+  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
+          path: reference
+      - run: tar -czf "flagsmith_${GITHUB_REF_NAME}_reference.tar.gz" reference
+      - 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.