Forgejo option runbook

Forgejo as the community-governed lightweight forge option for Managed Git Server

This is the Forgejo option runbook for Managed Git Server. Forgejo is for teams that want a self-hosted Git forge with transparent governance, private source-control operations, and a documented boundary between platform operations and repository workflow ownership.

Forgejo is selected after assessing governance preferences, Gitea-family compatibility, release cadence, hosting location, Actions runner behavior, backup expectations, identity integration, and provider evidence needs.

Best-fit use cases#

Deployment options#

Managed operating scope#

Access and identity#

The onboarding runbook should define the identity provider, local-account policy, emergency admin access, team and repository ownership model, SSH key rules, token and bot-account policy, repository visibility, deletion approvals, audit-log retention, and privileged access review process. Assistance can operate identity integration and platform-side controls, but the customer decides who may access repositories, secrets, protected branches, packages, and deployment environments.

Backups, upgrades, and monitoring#

A production Forgejo service should have a runbook covering database, Git repositories, LFS objects, packages, attachments, hooks, and configuration backups; encryption and storage location; restore procedure and validation cadence; upgrade source and version policy; maintenance windows; rollback criteria; runner compatibility checks; dashboards, alerts, severity levels, and evidence retention. Assistance should not claim recovery guarantees until restore behavior has been validated or explicitly scoped.

Forgejo Actions and custom runners#

Forgejo can be paired with Assistance custom runners when workflows need managed capacity, controlled isolation, private-network reachability, or documented operating evidence. Start with the Forgejo Actions runner guide, managed runners overview, and runner security hardening.

Runner selection is label-based. A simple validation workflow might target the default managed Linux pool:

1
jobs:
2
  smoke:
3
    runs-on: [self-hosted, linux, x64]
4
    steps:
5
      - uses: actions/checkout@v4
6
      - run: uname -a

Private-network or deployment jobs should use a distinct label set:

1
jobs:
2
  release:
3
    runs-on: [self-hosted, linux, x64, private-network, deploy]
4
    environment: production
5
    steps:
6
      - uses: actions/checkout@v4
7
      - run: ./scripts/release.sh

Labels should be stable, descriptive, and tied to approved trust levels. If a runner can reach production systems, internal package registries, or protected networks, that capability should be visible in its labels and reviewed before untrusted workflows can select it.

Registration tokens#

Forgejo runner registration tokens come from the customer's Forgejo environment and are scoped to the intended user, repository, organization, or instance boundary. Assistance receives them only through the approved secret exchange path, registers runners with the agreed labels and execution mode, redacts tokens from tickets and logs, and documents token handling in the runbook. Exposed tokens should be revoked or rotated.

Private-network runner profiles#

Private-network runners require an explicit design decision. The runbook should list approved subnets, VPNs, peering, DNS, certificate authorities, package mirrors, deployment endpoints, ports, egress policy, firewall owner, and labels that imply private reachability. Default build runners should not automatically inherit private-network access.

Workflow compatibility validation#

Forgejo Actions behavior depends on the Forgejo release, Actions settings, runner package, cache and artifact configuration, token permissions, and action compatibility. Assistance validates a smoke workflow first, then representative workflows for checkout, caches, artifacts, container builds, secrets, private services, and deployment approvals. Differences from GitHub Actions, GitLab CI/CD, or Gitea Actions are documented as tested environment behavior.

Onboarding workflow#

1. Assessment — Review hosting preference, Forgejo version or migration source, users, repositories, identity provider, data location, backup posture, runner scope, and governance constraints.
2. Operating design — Define topology, identity, backup and restore process, upgrade cadence, monitoring, support model, runner labels, private-network profiles, and responsibility boundaries.
3. Provision or take over — Deploy or stabilize Forgejo, configure TLS, SSH, mail, storage, identity, backups, observability, and Actions settings.
4. Runner integration — Register Assistance custom runners using approved tokens, labels, and execution profiles; validate low-risk workflows before production jobs depend on them.
5. Operate and improve — Maintain runbooks, schedule upgrades, review incidents, adjust capacity, validate restores, and update runner profiles as requirements change.

Responsibility boundaries#

Related docs and services#

• Forgejo Actions runners
• Managed runners overview
• Runner security hardening
• Runner monitoring
• Managed Git Server options
• Gitea option runbook
• GitLab option runbook
• Gerrit option runbook
• Managed runners service

Getting started#

Open a support or onboarding request with the desired Forgejo hosting model, repository count, identity provider, backup expectations, governance constraints, runner scope, label requirements, private-network needs, first workflow to validate, and preferred maintenance window. Assistance will confirm the operating boundary before taking over or changing production services.