Actions and CI/CD

fremforge runs Forgejo Actions, a GitHub Actions-compatible CI/CD system. Workflow files use GitHub Actions YAML syntax and approximately 95% of GitHub Marketplace actions work without modification.

Workflow file location

Place workflow files in .forgejo/workflows/<name>.yaml inside your repository. Forgejo also reads .github/workflows/ for compatibility with repositories migrated from GitHub, but .forgejo/workflows/ is the canonical location on fremforge.

Trigger events

Context variables

fremforge uses github.* context names for compatibility with the GitHub Actions ecosystem. These refer to the fremforge/Forgejo instance, not GitHub.

Built-in secrets

Built-in tokens are short-lived and scoped to the current workflow run. They cannot be used outside the job that received them.

Permissions block

The default permission set is contents: read. All other permissions default to none unless explicitly declared.

permissions:
  contents: read       # git checkout
  id-token: write      # OIDC token federation
  issues: write        # create / update issues
  pull-requests: write # comment on PRs

Declare permissions at the workflow level (applies to all jobs) or at the individual job level. Job-level declarations override workflow-level ones.

Minimal workflow example

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm ci && npm test

Reusable workflows

Extract common logic into a reusable workflow called by other workflows with workflow_call:

# .forgejo/workflows/reusable.yaml
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string

jobs:
  deploy:
    runs-on: fremforge
    environment: ${{ inputs.environment }}
    steps:
      - run: echo "Deploying to ${{ inputs.environment }}"

Call it from another workflow:

jobs:
  deploy-staging:
    uses: ./.forgejo/workflows/reusable.yaml@main
    with:
      environment: staging

Caching

Use actions/cache to persist directories between runs:

- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

Cache hits speed up jobs significantly for package managers, build tools, and compiled outputs. Cache is scoped per branch and falls back to the base branch on miss.

Environments and deployment gates

Environments add approval gates, required reviewers, and environment-scoped secrets to deploy jobs.

Create environments under Repo Settings → Environments. Configure required reviewers to require manual approval before the job runs.

Reference an environment in a job:

jobs:
  deploy-prod:
    runs-on: fremforge
    environment: production
    steps:
      - run: ./deploy.sh

If production has required reviewers configured, the job pauses for approval before executing. Secrets set on the production environment are injected only into this job.

Compatibility notes

• ~95% of GitHub Marketplace actions work without modification.
• secrets.GITHUB_TOKEN is an alias for secrets.FORGEJO_TOKEN. Actions using it work as-is.
• Actions that call the GitHub API directly (hardcoded api.github.com) will fail. The fremforge API URL is https://frem.sh/api/v1.
• actions/upload-artifact and actions/download-artifact work.
• GitHub Packages (ghcr.io, pkg.github.com) are not available. Use the fremforge package registry instead.
• Actions that require GitHub-specific features (GitHub Copilot, GitHub Codespaces, GitHub Packages) have no fremforge equivalent.

See Marketplace compatibility for the full top-100 action compatibility matrix.

Fork-PR secret reach — pull_request_target policy

pull_request_target runs workflows in the target repo’s context when a PR comes from a fork — meaning the workflow has access to the target repo’s secrets even though the workflow file may have been modified by the fork author. This is the exact attack shape that produced the GitHub Actions Marketplace 2023 incident class.

fremforge policy: workflows that use pull_request_target MUST NOT execute fork-supplied code with secrets present. Two acceptable patterns:

1. pull_request instead of pull_request_target when the workflow needs to run fork code. The fork-PR’s workflow runs in the fork’s context — no target-repo secrets reachable. This is the default and the safe shape.
2. pull_request_target ONLY for read-only labeller/triage/comment workflows that explicitly check out github.sha (the merge-base, not the fork head) and don’t run any fork-supplied install/build/test step.

Workflows that mix pull_request_target with actions/checkout@v4 against github.event.pull_request.head.sha are a SEV-1 secret-exfiltration vector and will be flagged by the pre-merge review. A pre-receive Forgejo hook that statically rejects the dangerous combination is on the future-hardening roadmap; until it ships, code-review is the active gate.

For full background: Forgejo Actions security model is the same as GitHub’s. The pull_request_target semantics are inherited unchanged.

Image-source policy

uses: statements come in two shapes — both are accepted on fremforge but the egress posture differs:

• uses: <owner>/<repo>@<sha> — resolved against the EU action mirror at frem.sh/<owner>/<repo> — each upstream publisher has its own mirror org (actions, docker, aws-actions, azure, google-github-actions, peter-evans, softprops, sonarsource, step-security, dorny, pnpm), so uses: actions/checkout@<sha> resolves to frem.sh/actions/checkout. Mirrors sync from upstream every 8h. This is the recommended shape.
• uses: docker://<registry>/<image>:<tag> — Forgejo Actions resolves this by pulling the image directly from the registry URL the workflow author specified. There’s no automatic rewrite to a fremforge mirror, and no built-in allowlist on the registry portion today. Pin to a digest (docker://<registry>/<image>@sha256:…) rather than a mutable tag. A pre-receive Forgejo hook or runner-side allowlist for docker:// is on the future-hardening roadmap — until it ships, document the policy in your repo’s CONTRIBUTING.md and treat unpinned docker:// references as a code-review issue.

The workflow-run API

Four routes exist and work. Only the first two are documented anywhere else, which is why the other two are usually reported as missing:

# stop a run that is queued or in progress
curl -X POST -H "Authorization: token <forgejo-pat>" \
  https://frem.sh/api/v1/repos/<owner>/<repo>/actions/runs/<run_id>/cancel
# -> 204, and the run's status becomes `cancelled`

Why cancel looks like it does not exist

Every signal points away from it, so “I could not find it” is the expected outcome rather than a failure to look:

• DELETE returns 405. The route is POST only. DELETE .../cancel and both verbs on .../runs/<id> (without /cancel) all return 405.
• /actions/tasks/<id>/cancel returns 404. Tasks are not runs.
• Forgejo’s own OpenAPI spec is not served here. /swagger.v1.json and every variant of it return 404 on frem.sh, so there is nothing to look the route up in.
• The fremforge api spec does not describe it, and cannot. It documents this platform’s endpoints, not Forgejo’s — cancel appears in it only under /orgs/{org}/billing/cancel, which is subscriptions. Searching it for a way to cancel a run finds the wrong cancel.
• The fremforge api answers 501. That is the catch-all for /api/v1/* paths matching no endpoint, and its message points at the fremforge OpenAPI spec — i.e. back to the spec that does not contain this route.
• ffp_* tokens cannot do it at all. The org-scoped proxy bridges the logs route only (see below); cancel and re-run need a Forgejo PAT or session cookie.

If you are cancelling runs by hand more than once

Do not script it — set a concurrency group instead, so Forgejo cancels the superseded run itself:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Every push to a branch then supersedes its own previous run. Safe for required checks: statuses are per-commit, so cancelling the run for an older commit cannot leave the current head’s checks hanging.

A cancelled run leaves its checks pending, not failed. So cancelling a run on the commit you are trying to merge will hang an armed auto-merge forever — it waits on a check that will never report again. Push, or POST .../rerun.

Fetching workflow logs programmatically

The Forgejo web UI shows action run logs interactively. For programmatic access (failure notifiers, debug scripts, compliance exports, AI agents triaging failures) there are two endpoints depending on which token type you hold:

With a Forgejo PAT or session cookie

curl -H "Authorization: token <forgejo-pat>" \
  https://frem.sh/api/v1/repos/<owner>/<repo>/actions/runs/<run_id>/logs

Returns text/plain — every job of the run concatenated, with === job: <name> (status=<status>, attempt=<n>) === headers between jobs. The <run_id> is the global id Forgejo returns from GET /api/v1/repos/<owner>/<repo>/actions/runs (the same id the web UI shows in /<owner>/<repo>/actions/runs/<n>). RBAC is Forgejo’s standard repo-read check; bot users with the right org membership work the same as human users.

With a fremforge api PAT (ffp_*)

If your token starts with ffp_ — including PATs minted in the admin UI, tokens received from POST /api/v1/auth/token-exchange (OIDC exchange), and tokens issued by POST /api/v1/oauth/token (client_credentials) — Forgejo doesn’t recognise it. Use the fremforge api proxy instead:

curl -H "Authorization: Bearer <ffp_…>" \
  https://frem.sh/api/v1/orgs/<org>/repos/<repo>/actions/runs/<run_id>/logs

Same response shape (text/plain, concatenated jobs, headers between them). Required scope: runners:read. The proxy verifies the token’s tenant binding (<org> in the URL must match the token’s tenant) before forwarding to Forgejo with a system credential — the system credential never leaves the platform, so a leaked customer PAT can only read its own tenant’s logs.

Both endpoints emit the same body, so a caller switching auth shapes only needs to change the URL and the Authorization header.

Workaround note. The /api/v1/orgs/<org>/repos/<repo>/... proxy is a temporary bridge until Forgejo upstream supports api-domain (ffp_*) tokens on its native /api/v1/repos/<owner>/<repo>/... endpoint. When that ships, the proxy is retired and ffp_* tokens will hit the same path as Forgejo PATs. The response shape stays identical; only the URL shape changes.

When logs are unavailable

• 404 — run not found, or not owned by the URL’s repo.
• 410 — logs have been purged by the cleanup job (action runs older than the retention window).
• 502 — Forgejo origin unreachable. Retry; if it persists, check status.frem.sh.

Cross-references

• CI runners, available runner labels, BYO runners, concurrency limits
• Secrets, secret scopes, rotation, OIDC as an alternative
• Marketplace compatibility, action compatibility matrix
• OIDC token federation, keyless cloud deployment from jobs
• Package registry, publishing packages from CI