Gitea Actions

Gitea Actions

Assistance designs and operates managed runner capacity for Gitea Actions inside the agreed cloud, network, repository, and data residency boundary. Gitea Actions is intentionally close to GitHub Actions workflow syntax, but it is not guaranteed to have full GitHub feature parity. Exact behavior depends on the customer's Gitea version, Actions configuration, 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 Gitea 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#

Gitea Actions managed runners are a good fit when a team already runs Gitea and wants Assistance to operate self-hosted CI/CD capacity with explicit ownership, monitoring, and change control.

Use them for:

• private repositories that need build capacity near self-hosted source control;
• EU-hosted or customer-hosted environments where data residency and network paths must be documented;
• workloads that need access to internal package registries, deployment targets, or private services;
• open-source or self-hosted governance models where the customer controls the forge and Assistance operates only the agreed runner layer;
• teams migrating selected jobs from GitHub Actions or GitLab runners without assuming complete feature parity.

Assistance does not treat Gitea Actions as a drop-in replacement for every GitHub Actions feature. Reusable workflows, marketplace action compatibility, cache behavior, service containers, permissions, and token semantics must be checked against the installed Gitea release and actions runner.

Support and version assumptions#

Before onboarding, Assistance confirms:

• the Gitea deployment URL, version, hosting model, and Actions feature status;
• the actions runner implementation and version in use;
• whether runners are registered at instance, organization, repository, or user scope;
• accepted labels, default images, execution mode, and isolation requirements;
• which workflow features are enabled by the customer environment.

Feature availability is customer-environment-specific. Assistance can document tested behavior and provide upgrade recommendations, but the customer owns the Gitea service lifecycle unless the statement of work says otherwise.

Labels and runner selection#

Gitea Actions selects runners with workflow runs-on labels. Assistance and the customer should agree a small label contract and keep it stable.

Example label set:

Keep labels descriptive rather than application-specific. If a job requires sensitive network access or privileged container behavior, use a separate label and approval path instead of silently broadening the default runner pool.

Runner registration and tokens#

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

Typical onboarding flow:

1. Customer confirms the Gitea scope for the runner: user, repository, organization, or instance.
2. Customer generates a runner registration token in Gitea for that scope.
3. Assistance installs or updates the actions runner in the agreed hosting environment.
4. Assistance registers the runner with the approved labels and execution mode.
5. Customer validates a non-production workflow that uses those labels.
6. Assistance records the runner ID, labels, owner, token handling notes, and support contacts in the runbook.

Registration tokens are not application secrets. They should still be time-boxed, redacted from tickets and logs, and rotated after accidental exposure. Long-lived personal access tokens should not be used for runner registration unless the customer has explicitly approved that pattern.

Workflow YAML examples#

Use runs-on to target Assistance-operated labels. Keep the first validation workflow small so runner selection, checkout, network paths, and logs are easy to inspect.

1
name: 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: Check runner context
13
        run: |
14
          uname -a
15
          pwd
16
17
      - name: Checkout
18
        uses: actions/checkout@v4
19
20
      - name: Run tests
21
        run: ./scripts/test.sh

For jobs that require approved private network access, use the dedicated label agreed during onboarding:

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

These examples assume the customer's Gitea version and actions runner support the referenced syntax and actions. If an action from the GitHub ecosystem fails, Assistance will verify whether it is compatible with the configured Gitea Actions runtime before proposing a replacement.

Container and image strategy#

Assistance defines the runner image strategy with the customer before production use:

• base operating system, patch cadence, installed language runtimes, and package managers;
• whether Docker or another container runtime is available to jobs;
• whether jobs run directly on the runner host, inside containers, or in ephemeral virtualized capacity;
• how build caches, tool caches, and container layers are retained or discarded;
• which registries, mirrors, and egress paths are approved.

Default images should be boring and reproducible. Application-specific tools belong in the repository workflow or a versioned project image unless Assistance has agreed to maintain them as part of the runner baseline.

Secrets, variables, and permissions#

Gitea repository, organization, and user secrets remain under customer control. Assistance can advise on naming, scoping, rotation, and masking, but does not own business secrets unless contracted separately.

Recommended boundaries:

• store deployment credentials in the narrowest Gitea scope that meets the workflow need;
• prefer environment-specific secrets over broad shared secrets;
• avoid printing secrets, tokens, or private URLs in shell traces;
• use separate runners or labels for high-trust deployment jobs;
• rotate secrets after runner compromise, label misuse, or accidental log exposure.

Where Gitea token permissions differ from GitHub Actions or GitLab CI/CD, document the exact customer-environment behavior in the runbook instead of assuming provider parity.

Private network access#

Private network access is an explicit design decision. Assistance can place managed runners in an approved subnet, VPN, VPC, VLAN, or peered network, but the customer must approve the reachable systems and data classification.

The runbook should record:

• allowed private endpoints and ports;
• DNS split-horizon or internal resolver requirements;
• outbound internet restrictions and proxy settings;
• firewall ownership and change approval path;
• whether production deployment targets require a separate runner label.

A runner with private access should not also be the default untrusted build runner unless the risk has been reviewed and accepted.

Artifacts and cache expectations#

Artifact and cache behavior depends on the Gitea version, server configuration, storage backend, and actions runner. Assistance will validate the exact behavior during onboarding and record what is supported.

Plan for:

• artifact retention and maximum size limits set by the customer Gitea deployment;
• cache availability and eviction behavior, if enabled;
• storage location and data residency implications;
• whether sensitive build outputs should be uploaded as artifacts at all;
• recovery expectations when a runner is replaced or cache storage is cleared.

Do not assume GitHub Actions cache semantics. If caching is required for performance, Assistance should prove it with a representative workflow and document the observed behavior.

EU hosting, security, and compliance evidence#

For EU-hosted or regulated environments, Assistance can provide operational evidence for the runner layer it operates, such as:

• runner location, hosting provider, and network boundary;
• patch and maintenance records;
• monitoring and alerting configuration;
• access control and operator approval records;
• incident notes, change records, and backup or rebuild procedures.

This evidence supports customer governance but does not create a compliance certification by itself. The customer remains responsible for legal interpretation, risk acceptance, repository content classification, and Gitea service governance.

Differences from GitHub and GitLab#

Compared with GitHub Actions, Gitea Actions may use similar workflow syntax but can differ in action compatibility, token behavior, hosted service integrations, cache support, and marketplace assumptions.

Compared with GitLab runners, Gitea Actions uses Actions-style workflows rather than .gitlab-ci.yml, and runner selection is label-based rather than GitLab tag-based. Compared with the Gerrit option runbook, Gitea workflows run as Actions jobs instead of Gerrit event-driven verification workers that report review labels.

Document migrations as tested behavior, not assumptions. Assistance can help map job intent, but each workflow should be validated on the customer's Gitea instance.

Upgrade and maintenance coordination#

Runner maintenance should be coordinated with both Gitea administrators and application teams. Changes that may affect workflow behavior include:

• Gitea server upgrades;
• actions runner upgrades;
• base image refreshes;
• container runtime changes;
• label additions or removals;
• firewall, DNS, proxy, or registry changes.

Assistance records maintenance windows, expected impact, rollback notes, and validation workflows. The customer approves production-impacting changes according to the support agreement.

Troubleshooting#

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

Escalation requests should include workflow URL, run ID, runner label set, approximate start time, recent changes, and sanitized logs.

Customer and Assistance responsibilities#

Related docs and services#

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

Getting started#

Open a support or onboarding request with the Gitea URL, version, runner scope, required labels, network requirements, compliance constraints, first workflow to validate, and preferred maintenance window. Assistance will confirm the operating boundary before registering or changing runners.