BlumeOps Docs

Create Release Artifact Workflow

3 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.

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:

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 for the full upload flow, or build-blumeops.yaml for the version bump logic only — it uploads to Forgejo releases, not generic packages).

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.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.eblu.me/eblume/-/packages but is not yet linked to the repo.

To link it:

  1. Go to https://forge.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.

Pushing a commit back to a protected main

Some release flows commit back to main (e.g. build-blumeops.yaml bumps docs_version + builds the changelog; cv-deploy.yaml bumps cv_version). 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.

The fix is to authenticate the push as a whitelisted user via a PAT, not the automatic token:

  1. Provision MAIN_PUSH_TOKEN (an eblume-owned PAT, scope write:repository) as an Actions secret — it is in forgejo_actions_secrets alongside the repo’s other secrets. The value lives in the blumeops 1Password vault (blumeops-main-push-token).

  2. Pass it to actions/checkout so it becomes the persisted git credential:

    - name: Checkout
  uses: actions/checkout@… # pinned
  with:
    fetch-depth: 0
    token: ${{ secrets.MAIN_PUSH_TOKEN }}

    Subsequent git push origin HEAD:main 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