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
  packages: write      # publish to package registry
  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/mirrors so the action source is always a fremverk-mirrored copy that’s been through SBOM + SAST + Trivy gates. New top-level actions are mirrored roughly hourly. 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.

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