CI runners

fremforge provides hosted runners included in every seat plan, and supports BYO runners for teams that need on-prem, custom hardware, or specific network placement. Both runner types execute Forgejo Actions workflows using the same GitHub Actions YAML syntax.

Hosted runners

Hosted runners are ephemeral, kernel-isolated compute provisioned on T Cloud Cloud Container Instance (CCI) in the eu-de region. Each job gets a fresh instance; nothing persists between runs.

Available labels

Reference a label in your workflow:

jobs:
  build:
    runs-on: fremforge

For container image builds, use the pre-installed kaniko (Docker-in-Docker is not available, see Container builds below):

jobs:
  build-image:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: |
          /usr/local/bin/kaniko \
            --context=$GITHUB_WORKSPACE \
            --dockerfile=Dockerfile \
            --destination=registry.example.com/$GITHUB_REPOSITORY:$GITHUB_SHA

ARM64 hosted runners and additional OS variants (Debian, Fedora, …) are on the Phase 2 roadmap, fremforge today targets x86_64 Linux only. BYO runners (see below) are the path for ARM64 or non-Linux workflows in the meantime.

Isolation model

Each job runs inside a dedicated CCI instance with its own kernel. There is no shared kernel between jobs in the same org, different orgs, or between concurrent runs of the same workflow. The host hypervisor is T Cloud’s CCI fleet in eu-de (Biere/Magdeburg).

Included minutes and concurrency

The concurrency limit is a soft limit. Contact support@frem.sh to raise it for your org. During platform-wide peak, a hard cap applies; jobs queue rather than fail.

Overage billing (opt-in): by default, new jobs queue when the pool is exhausted. Org owners can enable metered overage at Org admin → Billing → Runner minutes → Enable overage billing. When enabled, minutes above the pool are charged at €0,01/min on the next invoice. Overage can be disabled at any time from the same page.

Usage dashboard

Track runner minute consumption at Org admin → Billing → Runner usage.

The usage dashboard shows:

Minutes are counted from job start to job end, rounded up to the nearest second. Queue time (waiting for a runner) is not counted.

The monthly period resets on the 1st of each month UTC. Unused minutes do not roll over.

BYO runner minutes are tracked separately in the same dashboard and do not count against the hosted pool.

Alerts: set a usage alert at Org admin → Billing → Runner usage → Set alert. You receive an email when the org reaches the configured threshold (e.g., 80% of the monthly pool). Useful for orgs that have overage billing enabled and want advance warning before the pool is exhausted.

Runner image contents

The hosted runner image is rebuilt weekly. A Trivy CVE gate runs at build time. Any image with HIGH or CRITICAL findings is blocked from shipping until patched.

We deliberately keep the image lean (~280 MB compressed; GitHub’s ubuntu-latest is ~50 GB) by NOT pre-installing language toolchains. Customers pin specific language versions via standard setup-* actions, same UX as GitHub Actions, with the benefit of explicit per-workflow version pinning rather than implicit drift on the host image.

Pre-installed:

Use setup-* actions for: Python, Go, Rust, Java, .NET, Ruby, PHP, kubectl, helm, cloud CLIs (T Cloud OTC CLI, AWS CLI, Azure CLI, gcloud).

The full manifest with exact resolved versions + SWR digest + Trivy scan summary + CycloneDX SBOM is posted to the fremforge changelog with each weekly image rebuild.

Container builds (no Docker-in-Docker)

Our runner pods run on T Cloud Cloud Container Instance (CCI) v2, which doesn’t permit privileged containers, Docker-in-Docker is therefore not possible. Use the pre-installed kaniko instead for rootless OCI image builds:

- name: Build + push image
  run: |
    /usr/local/bin/kaniko \
      --context=$GITHUB_WORKSPACE \
      --dockerfile=Dockerfile \
      --destination=registry.example.com/$GITHUB_REPOSITORY:$GITHUB_SHA

For pure image copy (e.g. retag-and-push between registries), apk add skopeo works in a run: step.

For full per-tool details see docs.frem.sh/build/actions/runner-image/.

BYO runners

Register your own runners against any fremforge org (on-prem servers, cloud VMs, Mac minis, Raspberry Pis). BYO runner minutes do not count against the hosted pool.

Registration

1. Go to Org admin → Settings → Runners → New runner.
2. Copy the registration token.
3. Download the Forgejo runner binary. The current stable release is published at code.forgejo.org/forgejo/runner/releases, pin to a recent tag when you install:

# Linux x86_64 — replace <version> with the tag from the releases page (e.g. v6.4.0)
curl -sSL https://code.forgejo.org/forgejo/runner/releases/download/<version>/forgejo-runner-<version>-linux-amd64 \
  -o forgejo-runner && chmod +x forgejo-runner

# macOS arm64
curl -sSL https://code.forgejo.org/forgejo/runner/releases/download/<version>/forgejo-runner-<version>-darwin-arm64 \
  -o forgejo-runner && chmod +x forgejo-runner

fremforge tracks current Forgejo releases; runners on older binaries continue to work but should be upgraded within a release cycle to pick up CVE patches.

4. Register the runner:

./forgejo-runner register \
  --instance https://frem.sh \
  --token <registration-token> \
  --name my-runner \
  --labels linux,self-hosted,my-custom-label

5. Start the runner:

./forgejo-runner daemon

Supported platforms

Custom labels

Labels assigned at registration are what you reference in runs-on::

jobs:
  deploy:
    runs-on: [self-hosted, my-custom-label]

Multiple labels in a list mean “find a runner that has ALL of these labels”. The self-hosted label is conventional. Include it to avoid accidentally routing a BYO job to a hosted runner.

Don’t use reserved labels. The labels fremforge, fremforge-cci, cci, and linux/amd64 route to our hosted-runner pool. Pick distinct labels for your BYO runners (e.g. self-hosted, on-prem, my-team-runner) so workflows can address them unambiguously.

Network requirements for the runner host

The runner binary opens long-poll HTTPS connections to https://frem.sh and clones repositories over HTTPS. From the host’s perspective the connectivity requirement is:

No inbound connectivity is needed — the runner initiates all connections outbound. A runner behind NAT or a firewall works fine as long as it can reach frem.sh:443.

Security and isolation responsibility

For hosted runners, fremforge provides kernel-level isolation between jobs (each job runs in a fresh CCI micro-VM). For BYO runners, isolation is your responsibility. A self-hosted runner that handles workflows from multiple repositories shares state across jobs unless you scope each runner to a single repository or org.

If you run workflows from multiple teams or trust-domains, treat your BYO runner the same way GitHub Actions self-hosted runners are treated:

• One runner per repository (or per trust-boundary) when secrets are sensitive.
• Don’t register a BYO runner against a public repository — anyone with merge access could land a workflow change that executes arbitrary code on your runner host.
• Treat the runner host as production: harden the OS, keep the runner binary patched, and route its egress through your own SSRF / egress controls.

The fremforge SSRF outbound proxy does NOT apply to BYO runners — only to hosted runners. Your runner’s network policy is whatever you wire on the host.

Egress and network

Org-level egress allowlist: to allow outbound access to additional CIDRs or ports from runner jobs, contact support@frem.sh. Egress rules are configured at the platform level.

The SSRF proxy is a platform floor. It cannot be disabled. It prevents runner jobs from reaching T Cloud instance metadata or internal infrastructure.

Secrets in jobs

Secrets are injected as environment variables and masked in job logs. Any log line containing a secret value is replaced with ***.

Reference syntax:

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.MY_API_KEY }}
    run: ./deploy.sh

Secret scopes

Environment secrets require the job to declare an environment:

jobs:
  deploy:
    runs-on: fremforge
    environment: production
    steps:
      - run: echo ${{ secrets.PROD_API_KEY }}

For cloud provider credentials, prefer OIDC token federation over long-lived secrets. No secret to store, no secret to rotate.

Troubleshooting

Job is stuck in queue.

The most common cause is hitting the concurrent-job cap (2/seat, max 100/org). Check Org admin → Billing → Runner usage for current active job count. If you are at the cap, either wait for a running job to finish, add more seats (which raises the cap proportionally), or contact support@frem.sh for an Enterprise-on-Demand uplift.

docker command not found in job.

Hosted fremforge runners do NOT include the Docker daemon or the docker CLI, CCI v2 (the underlying T Cloud runtime) doesn’t permit privileged containers, so Docker-in-Docker is not possible. For container image builds, use the pre-installed kaniko (see Container builds). For pure image copy/retag/push between registries, apk add skopeo works in a run: step.

Secret is masked in logs but the step behaves as if it is empty.

The secret exists in the runtime (masking confirms this), but the value at the correct scope is not set. Check:

1. Is the secret set at org level, repo level, or environment level?
2. If it is an environment secret, does the job declare environment: <name> matching the secret’s environment?
3. Is the secret name spelled exactly right (case-sensitive)?

The Secrets UI at the relevant scope shows the secret name and last-updated timestamp. Use that to confirm the secret exists before looking at the workflow.

Cross-references

• OIDC token federation, keyless cloud auth from CI jobs
• Secrets, managing org, repo, and environment secrets
• Marketplace compatibility, which GitHub Marketplace actions work on fremforge runners
• AI posture, what AI tooling is and is not present in the runner environment