Gitea option runbook

Gitea as the lightweight forge option for Managed Git Server

This is the Gitea option runbook for Managed Git Server. Gitea is for teams that want a compact self-hosted Git forge for private repositories, small-to-medium engineering groups, internal tooling, or environments where source code and CI/CD traffic should stay inside a defined operating boundary.

Gitea is selected after assessing repository scale, governance requirements, identity, hosting location, Actions compatibility, runner trust levels, backup expectations, and provider evidence needs.

Best-fit use cases#

Deployment options#

Managed operating scope#

Access and identity#

Before go-live, Assistance and the customer document the authoritative identity provider, fallback admin process, organization and repository ownership groups, SSH key and token policy, repository visibility rules, emergency access handling, and audit-log evidence expectations. Assistance can implement the platform-side identity integration, but customer leadership remains responsible for who should have access to code, packages, deployment credentials, and protected branches.

Backups, upgrades, and monitoring#

Production Gitea should have an operational runbook for repository, database, package, LFS, attachment, and configuration backups; retention and restore validation; version upgrade windows; rollback criteria; health checks; storage growth; mail, SSH, and certificate monitoring; and incident escalation. Backup existence is not enough: restore expectations, owner approvals, and recovery-time assumptions should be tested or explicitly marked out of scope.

Gitea Actions and custom runners#

The Gitea option can be paired with Assistance custom runners for controlled CI/CD capacity. Start with the Gitea Actions runner guide, the managed runners overview, and runner security hardening.

Runner integration is designed around an explicit label contract. A typical workflow targets Assistance-operated capacity with runs-on labels such as:

1
jobs:
2
  test:
3
    runs-on: [self-hosted, linux, x64]
4
    steps:
5
      - uses: actions/checkout@v4
6
      - run: ./scripts/test.sh

Use separate labels for higher-trust work:

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

Assistance and the customer should agree which labels imply private network access, elevated resource profiles, container privileges, production deployment reachability, or stronger approval requirements. Do not silently broaden a default runner pool to reach private systems.

Registration tokens#

Gitea runner registration tokens are generated by the customer's Gitea environment for the selected user, repository, organization, or instance scope. Assistance handles them through the agreed secret exchange channel, registers the runner with approved labels, and records the runner identity and scope in the runbook. Tokens should be short-lived where possible, redacted from tickets and logs, and rotated after exposure.

Private-network runner profiles#

Private-network runners are placed in approved subnets, VPNs, VLANs, peered networks, or customer cloud segments. The runbook should list reachable endpoints, ports, DNS resolver behavior, certificate trust, egress restrictions, firewall owner, and which labels select that profile.

Workflow compatibility validation#

Gitea Actions is close to GitHub Actions syntax, but compatibility depends on the Gitea version, Actions configuration, and runner implementation. Assistance validates a small smoke workflow first, then representative workflows for checkout, caches, artifacts, container builds, secrets, private network access, and deployment approvals. Unsupported actions or syntax are documented as environment-specific findings rather than assumed provider parity.

Onboarding workflow#

1. Assessment — Review hosting preference, Gitea version or migration source, users, repositories, identity provider, data location, backup expectations, runner needs, and first workflows to validate.
2. Operating design — Define topology, access model, backup and restore process, upgrade cadence, monitoring, runner labels, private-network profiles, and responsibility boundaries.
3. Provision or take over — Deploy or stabilize Gitea, configure identity, TLS, SSH, storage, mail, backups, alerts, and Actions settings.
4. Runner integration — Register Assistance custom runners with approved labels, handle registration tokens safely, and validate non-production workflows.
5. Go-live and operate — Record runbooks, contacts, support windows, change workflow, incident process, and evidence expectations.

Responsibility boundaries#

Related docs and services#

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

Getting started#

Open a support or onboarding request with the desired Gitea hosting model, repository count, identity provider, backup expectations, 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.