Forgejo Actions

Forgejo Actions

Assistance designs and operates managed runner capacity for Forgejo Actions inside the agreed cloud, network, repository, and data residency boundary. Forgejo is an open-source, self-hosted forge, and its Actions support is version- and configuration-dependent. Exact runner behavior depends on the customer's Forgejo release, Actions settings, and deployed actions runner.

Use this page with the managed runners overview, runner security hardening, monitoring guidance, and runner troubleshooting. If Assistance also operates the Forgejo server, keep runner labels, registration scope, token handling, private-network access, and workflow compatibility notes in the managed git server handoff so repository owners can navigate back to this runner guide.

When to use this#

Forgejo Actions managed runners are a good fit when a team wants CI/CD capacity for a Forgejo deployment while keeping clear control over hosting, governance, and data residency.

Use them for:

• self-hosted Forgejo repositories that need managed build and deployment capacity;
• open-source or cooperative governance models where infrastructure ownership must be transparent;
• EU-hosted deployments where source code, logs, artifacts, and runner access paths must stay within agreed boundaries;
• private-network deployments to internal registries, staging systems, or production targets;
• migrations or dual-running from GitHub Actions, GitLab runners, or Gitea Actions with feature checks instead of assumed parity.

Assistance does not claim Forgejo Actions is a complete substitute for every GitHub Actions or GitLab CI/CD capability. Workflow syntax, marketplace action compatibility, cache behavior, token permissions, and container support must be validated against the customer's Forgejo environment.

Support and version assumptions#

Before onboarding, Assistance confirms:

• the Forgejo deployment URL, version, hosting model, and Actions status;
• the actions runner package, version, installation method, and upgrade source;
• whether runner registration is at instance, organization, repository, or user scope;
• allowed labels, execution mode, base image policy, and isolation expectations;
• enabled workflow features, artifact storage, cache support, and known limitations.

Forgejo and runner behavior can change across versions. Assistance records tested behavior for the customer environment and coordinates upgrade validation, but the customer owns the Forgejo service lifecycle unless operations ownership is explicitly contracted.

Labels and runner selection#

Forgejo Actions selects self-hosted runners with workflow runs-on labels. Assistance and the customer should agree a small label contract before production workflows depend on it.

Example label set:

Avoid overloading one runner pool with conflicting trust levels. If a workflow can deploy to production, give it a dedicated label and approval path rather than sharing the default build runner.

Runner registration and tokens#

Runner registration uses tokens generated by the customer's Forgejo environment. At a user level, the customer or an approved Assistance operator should generate a short-lived registration token for the intended scope and pass it through the agreed secret exchange channel.

Typical onboarding flow:

1. Customer confirms the Forgejo scope for the runner: user, repository, organization, or instance.
2. Customer generates a runner registration token for that scope.
3. Assistance provisions or updates the runner host, container, or virtualized environment.
4. Assistance registers the runner with the approved labels and execution mode.
5. Customer validates a low-risk workflow using the new labels.
6. Assistance records runner identity, labels, scope, token handling, monitoring, and support contacts in the runbook.

Registration tokens should be redacted from tickets, terminal captures, and logs. If a token is exposed, revoke or rotate it and re-register affected runners according to the customer runbook.

Workflow YAML examples#

Start with a small smoke test that proves runner matching, checkout, and shell execution.

1
name: forgejo-runner-smoke
2
3
on:
4
  push:
5
    branches: [main]
6
  workflow_dispatch:
7
8
jobs:
9
  smoke:
10
    runs-on: [self-hosted, linux, x64]
11
    steps:
12
      - name: Show runner context
13
        run: |
14
          uname -a
15
          whoami
16
17
      - name: Checkout
18
        uses: actions/checkout@v4
19
20
      - name: Run project tests
21
        run: ./scripts/test.sh

For deployment or private-network work, target a dedicated label that Assistance has placed in the approved network boundary:

1
name: internal-release
2
3
on:
4
  workflow_dispatch:
5
6
jobs:
7
  release:
8
    runs-on: [self-hosted, linux, x64, private-network, deploy]
9
    environment: production
10
    steps:
11
      - uses: actions/checkout@v4
12
      - name: Publish release
13
        run: ./scripts/release.sh

These examples intentionally use common Actions-style syntax. If a referenced action or field fails, Assistance will verify whether the customer's Forgejo version and runner support it before changing the workflow.

Container and image strategy#

The runner image strategy is part of the operating boundary. Assistance documents:

• base operating system and patch cadence;
• installed runtimes, CLIs, package managers, and trust anchors;
• whether jobs may use Docker, Podman, nested containers, or service containers;
• registry access, image provenance, and allowed mirrors;
• workspace cleanup, cache directories, and disk quotas;
• whether runners are long-lived, ephemeral, containerized, or VM-backed.

Keep the baseline small and reproducible. If a repository needs specialized build tools, prefer a versioned project container image or workflow setup step unless Assistance has agreed to maintain those tools globally.

Secrets, variables, and permissions#

Customer teams own Forgejo secrets, variables, repository permissions, and approval rules. Assistance can provide guidance and runner-side controls, but does not own secret values unless that is part of the contract.

Recommended practices:

• scope secrets to the smallest repository, organization, user, or environment boundary available;
• separate build, staging, and production credentials;
• avoid broad tokens copied from GitHub or GitLab without permission review;
• keep deployment jobs on separately labeled runners when they require higher trust;
• rotate secrets after accidental log exposure, runner compromise, or team membership changes.

Token permissions and masking behavior must be verified in the customer's Forgejo version. Do not assume GitHub GITHUB_TOKEN or GitLab CI_JOB_TOKEN semantics apply unchanged.

Private network access#

Private network access is not a default property of all managed runners. Assistance can operate runners inside approved networks, but the customer must approve reachable services and the data classification of those paths.

Document:

• subnets, VPNs, peering, or firewall zones used by runners;
• internal DNS and certificate authority requirements;
• allowed registries, package mirrors, deployment endpoints, and ports;
• egress restrictions, proxies, and inspection points;
• which labels imply private or production access.

For open-source projects, take extra care that untrusted pull requests cannot run on runners with private-network or deployment labels unless the customer's governance model explicitly permits it.

Artifacts and cache expectations#

Artifact and cache behavior is Forgejo-environment-specific. Assistance validates the configured behavior and records it in the runbook instead of assuming GitHub Actions parity.

Confirm:

• whether artifacts are enabled, where they are stored, and retention limits;
• whether workflow caches are enabled and how keys are matched or evicted;
• maximum upload size and expected cleanup behavior;
• whether artifact or cache storage stays inside the agreed EU or customer-hosted boundary;
• which outputs are too sensitive to upload.

If cache performance is a business requirement, Assistance should prove it with representative jobs and publish the measured before-and-after impact.

EU hosting, security, and compliance evidence#

Forgejo is often selected because teams want self-hosted control. Assistance can support that governance model by producing evidence for the runner layer it operates:

• hosting location, provider, and data residency boundary;
• runner inventory, labels, and registration scope;
• operator access records and approval path;
• patch, image refresh, and maintenance records;
• monitoring alerts, incident timelines, and recovery notes;
• network diagrams or endpoint allowlists for private access.

This evidence helps customer audits and security reviews. It does not replace legal advice, regulatory certification, or customer risk acceptance for the Forgejo service, repository content, or business process.

Differences from GitHub, GitLab, and Gitea#

Compared with GitHub Actions, Forgejo Actions may look familiar but can differ in hosted integrations, action marketplace assumptions, default tokens, permissions, caches, and runner behavior.

Compared with GitLab runners, Forgejo uses Actions-style workflow files and runs-on labels rather than .gitlab-ci.yml and GitLab runner tags. Compared with the Gerrit option runbook, Forgejo workflows run as Actions jobs instead of Gerrit event-driven verification workers that report review labels.

Compared with Gitea Actions, Forgejo support depends on the specific Forgejo release and runner packaging selected by the customer. Treat both as related self-hosted forge platforms, not as identical operational surfaces.

Upgrade and maintenance coordination#

Coordinate runner changes with Forgejo administrators and repository owners. Production-impacting changes include:

• Forgejo server upgrades;
• actions runner upgrades or packaging changes;
• base image and runtime updates;
• container runtime or privilege policy changes;
• label contract changes;
• firewall, DNS, proxy, registry, or certificate changes.

Assistance prepares validation workflows, expected impact, rollback notes, and maintenance-window communications. The customer approves the timing and risk acceptance for production-impacting changes.

Troubleshooting#

Start with common runner errors, then collect Forgejo-specific evidence:

Escalation requests should include workflow URL, run ID, repository, runner labels, approximate start time, recent Forgejo or runner changes, and sanitized logs.

Customer and Assistance responsibilities#

Related docs and services#

• Managed runners overview
• Runner security hardening
• Runner monitoring
• Runner troubleshooting
• Gitea Actions
• GitHub Actions
• GitLab runners
• Gerrit option runbook
• Managed runners service
• CI/CD audit

Getting started#

Open a support or onboarding request with the Forgejo URL, version, runner scope, desired labels, network requirements, governance constraints, first workflow to validate, and maintenance-window preference. Assistance will confirm the operating boundary before registering or changing runners.