BlumeOps Docs

Create Release Artifact Workflow

5 min read

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.

Deprecated: this FORGE_TOKEN generic-package publish pattern is retired. The cv package now goes through the horkos publisher → zot (see eblume/horkos#17); this doc is kept for the historical shape. The Forgejo packages registry itself is now disabled on indri ([packages] ENABLED = false), so the /api/packages/ calls in this doc return 404 everywhere, not just at the public edge.

Prerequisites

  • A Forgejo repo with a build pipeline (Dagger, script, etc.)
  • The FORGE_TOKEN Forgejo Actions secret (this pattern predates the in-code values half; the retired forgejo_actions_secrets Ansible role used to provision it — set the secret via the forge UI or API)

1. The repo’s FORGE_TOKEN secret

Actions-secret names are now declared in forge/actions-secrets.json and their values applied from 1Password by mise run forge-reconcile (see forgejo’s Actions Secrets section). This pattern’s FORGE_TOKEN predates that mechanism and is not declared there: set the secret via the forge UI or API (the reference repo cv declares no secrets, so the next human apply of forge-reconcile deletes it). That 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 for the full upload flow).

The upload step uses FORGE_TOKEN:

- 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}"

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. This keeps the build/release concern in the source repo and the deploy concern in blumeops (for the retired version of this pattern, see cv-deploy.yaml in git history; the current flow goes through the horkos publisher → zot, eblume/horkos#17).

Pushing a commit back to a protected main

Some release flows commit back to main (e.g. the horkos publisher’s PR bumps the cv_version pin — see eblume/horkos#17; the now-deleted build-blumeops.yaml used to bump docs_version + build the changelog here, but that push is retired). main on blumeops is branch-protected with a push whitelist limited to eblume, and the automatic Forgejo Actions token cannot be push-whitelisted (Forgejo #11159) — so a plain git push origin HEAD:main is rejected with pre-receive hook declined.

Don’t rely on unprotected_file_patterns to let the Actions token push to a protected branch: Forgejo’s pre-receive handler resolves the pusher by user ID before it evaluates the exemption, and the synthetic Actions user (uid -2) doesn’t exist in the users table, so the hook 500s and the push is declined before the exemption is ever consulted. Gitea fixed this upstream in go-gitea/gitea#39564, Forgejo had not backported it as of 2026-10-13 (eblume/blumeops#1585). The whitelisted PAT push described below is the only supported way for an Actions workflow to push to protected main.

Retired (2026-10): this main-push half is what the release-PR model abolishes — the release PR carries the changelog and the docs_version bump to main itself, and the release workflow tags from the push to main instead of pushing main from CI (eblume/blumeops#1628). Kept below for the historical shape.

The fix is to authenticate the push as a whitelisted user via a PAT, not the automatic token. The PAT is no longer an Actions secret: per-purpose CI secrets were retired in favor of job-time op read of the blumeops-ci vault (blumeops-ci-item-migration), so the now-deleted build-blumeops.yaml used to read the eblume-owned main-push PAT (item blumeops-ci/forge-main-push/token, scope write:repository) at push time with the BLUMEOPS_CI_OP_TOKEN service account, and push with it directly — checkout runs with persist-credentials: false, so no credential sits in the worktree:

- name: Commit release changes
  env:
    OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.BLUMEOPS_CI_OP_TOKEN }}
  run: |
    MAIN_PUSH_TOKEN=$(op read 'op://blumeops-ci/forge-main-push/token')
    echo "::add-mask::$MAIN_PUSH_TOKEN"
    git -c credential.helper= push \
      "https://eblume:${MAIN_PUSH_TOKEN}@forge.ops.eblu.me/eblume/blumeops.git" \
      HEAD:main

The push then authenticates as eblume and passes branch protection. The release-creation API call can keep using the automatic GITHUB_TOKEN (API actions aren’t gated by the push whitelist); only the git push needs the PAT.

The commit author can stay Forgejo Actions — branch protection checks the pusher (the PAT owner), not the commit author.

Graph View

Backlinks