From 545433055eb550c4b8ee58f801ee222e7532cb7a Mon Sep 17 00:00:00 2001
From: Erich Blume <blume.erich@gmail.com>
Date: Thu, 12 Feb 2026 11:20:05 -0800
Subject: [PATCH] Add release artifact workflow how-to and changelog fragments
 (#170)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
- How-to guide for creating release artifact workflows with Forgejo packages
- Changelog fragment for the multi-repo forgejo_actions_secrets Ansible role change
- Changelog fragment for the new docs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/170
---
 docs/changelog.d/multi-repo-secrets.infra.md  |  1 +
 docs/changelog.d/release-artifact-docs.doc.md |  1 +
 .../create-release-artifact-workflow.md       | 74 +++++++++++++++++++
 docs/how-to/how-to.md                         |  1 +
 4 files changed, 77 insertions(+)
 create mode 100644 docs/changelog.d/multi-repo-secrets.infra.md
 create mode 100644 docs/changelog.d/release-artifact-docs.doc.md
 create mode 100644 docs/how-to/create-release-artifact-workflow.md

diff --git a/docs/changelog.d/multi-repo-secrets.infra.md b/docs/changelog.d/multi-repo-secrets.infra.md
new file mode 100644
index 0000000..ffeeef9
--- /dev/null
+++ b/docs/changelog.d/multi-repo-secrets.infra.md
@@ -0,0 +1 @@
+Extend forgejo_actions_secrets Ansible role to support multiple repos.
diff --git a/docs/changelog.d/release-artifact-docs.doc.md b/docs/changelog.d/release-artifact-docs.doc.md
new file mode 100644
index 0000000..2d6d779
--- /dev/null
+++ b/docs/changelog.d/release-artifact-docs.doc.md
@@ -0,0 +1 @@
+Add how-to guide for creating release artifact workflows with Forgejo packages.
diff --git a/docs/how-to/create-release-artifact-workflow.md b/docs/how-to/create-release-artifact-workflow.md
new file mode 100644
index 0000000..829ff3e
--- /dev/null
+++ b/docs/how-to/create-release-artifact-workflow.md
@@ -0,0 +1,74 @@
+---
+title: Create Release Artifact Workflow
+modified: 2026-02-12
+tags:
+  - how-to
+  - forgejo
+  - ci
+---
+
+# Create a Release Artifact Workflow
+
+How to set up a Forgejo Actions workflow that builds an artifact and publishes it to Forgejo generic packages. Uses the CV repo (`forge.ops.eblu.me/eblume/cv`) workflow as the reference implementation.
+
+## Prerequisites
+
+- A Forgejo repo with a build pipeline (Dagger, script, etc.)
+- The `FORGE_TOKEN` secret provisioned via the `forgejo_actions_secrets` Ansible role
+
+## 1. Add the repo to Ansible secrets
+
+In `ansible/roles/forgejo_actions_secrets/defaults/main.yml`, add an entry under `forgejo_actions_secrets_repos`:
+
+```yaml
+forgejo_actions_secrets_repos:
+  - repo: my-repo
+    secrets:
+      - name: FORGE_TOKEN
+        value_var: forgejo_api_token
+```
+
+Then provision: `mise run provision-indri -- --tags forgejo_actions_secrets`
+
+This is required because Forgejo's built-in `GITHUB_TOKEN` does not have permissions for the packages API.
+
+## 2. Create the workflow
+
+Create `.forgejo/workflows/<name>-release.yaml` with `workflow_dispatch` and a version input. Use the semver bump pattern (see `cv-release.yaml` or `build-blumeops.yaml` for examples).
+
+The upload step uses `FORGE_TOKEN`:
+
+```yaml
+- name: Upload to Forgejo packages
+  env:
+    FORGE_TOKEN: ${{ secrets.FORGE_TOKEN }}
+  run: |
+    curl -fsSL \
+      -X PUT \
+      -H "Authorization: token $FORGE_TOKEN" \
+      --upload-file "./$TARBALL" \
+      "https://forge.ops.eblu.me/api/packages/eblume/generic/<package>/${VERSION}/${TARBALL}"
+```
+
+## 3. Link the package to the repo
+
+After the first successful upload, the package appears under your **user-level** packages at `https://forge.ops.eblu.me/eblume/-/packages` but is not yet linked to the repo.
+
+To link it:
+
+1. Go to `https://forge.ops.eblu.me/eblume/-/packages`
+2. Click the package name
+3. Click **Settings**
+4. Under **Link this package to a repository**, select the repo
+5. Click **Save**
+
+Once linked, the package shows up in the repo's **Packages** tab and the repo links back to the package.
+
+## 4. Create a deploy workflow (optional)
+
+If the artifact is consumed by a k8s deployment, create a separate deploy workflow in blumeops (see `cv-deploy.yaml`). This keeps the build/release concern in the source repo and the deploy concern in blumeops.
+
+## Related
+
+- [[deploy-k8s-service]] - Deploying the service that consumes the artifact
+- [[add-ansible-role]] - Adding Ansible roles
diff --git a/docs/how-to/how-to.md b/docs/how-to/how-to.md
index 1b141c9..dfce173 100644
--- a/docs/how-to/how-to.md
+++ b/docs/how-to/how-to.md
@@ -15,6 +15,7 @@ Task-oriented instructions for common BlumeOps operations. These guides assume y
 |-------|-------------|
 | [[deploy-k8s-service]] | Deploy a new service to Kubernetes via ArgoCD |
 | [[add-ansible-role]] | Add a new Ansible role for indri services |
+| [[create-release-artifact-workflow]] | Build artifacts and publish to Forgejo packages |
 
 ## Configuration