agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/gitea-runner/SKILL.md

gitea-runner

Skill4 starsChanged 5 months agoMITView on GitHub

Use when configuring Gitea Actions runners — registration, deployment modes, Docker vs host mode, Talos/Kubernetes host-mode, ephemeral runners, and v1.26 Actions features.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Gitea Runner (v1.0.6)

Formerly act_runner. Renamed in v1.0.0 (May 2026). Binary: gitea-runner. Image: gitea/runner. Latest: v1.0.6.

Registration

Tokens at instance/admin, org, or repo level in Settings > Actions > Runners.

# Interactive
gitea-runner register

# Non-interactive
gitea-runner register --no-interactive \
  --instance https://git.example.com \
  --token <token> \
  --name my-runner \
  --labels ubuntu-latest:docker://node:20-bookworm

# Ephemeral (single-job runner, then exits)
gitea-runner register --no-interactive --ephemeral \
  --instance https://git.example.com \
  --token <token>

Token also via CLI: gitea --config /etc/gitea/app.ini actions generate-runner-token.

Running

gitea-runner daemon --config config.yaml

Generate default config: gitea-runner generate-config > config.yaml.

Labels Format

<label>:<scheme>://<image>
  • :host suffix — runs step on host (no Docker required)
  • :docker://image — runs step in container
  • ubuntu-latest:docker://node:20-bookworm — label ubuntu-latest runs in node:20-bookworm container

Deployment Modes

ModeDescriptionDocker Required
HostSteps run directly on host processNo
DockerSteps in sibling containers via socketYes (/var/run/docker.sock)
DinDRootless, own Docker daemon in containerYes (privileged container)

Kubernetes / Talos (Host Mode)

Talos has no Docker socket. Must use host mode with :host labels:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitea-runner
  namespace: gitea
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gitea-runner
  template:
    metadata:
      labels:
        app: gitea-runner
    spec:
      containers:
        - name: runner
          image: gitea/runner:latest
          env:
            - name: GITEA_INSTANCE_URL
              value: https://git.example.com
            - name: GITEA_RUNNER_REGISTRATION_TOKEN
              valueFrom:
                secretKeyRef:
                  name: runner-token
                  key: token
            - name: GITEA_RUNNER_LABELS
              value: "ubuntu-latest:host"

Runner container must include tools its workflows need (curl, git, node, etc.).

Docker Mode

docker run -d \
  -e GITEA_INSTANCE_URL=https://git.example.com \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=<token> \
  -e GITEA_RUNNER_NAME=runner-1 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitea/runner:latest

Ephemeral Runners

Set GITEA_RUNNER_EPHEMERAL=1. Runner runs exactly one job then exits. Use workflow_job webhook to autoscale (spin up new runner per job).

v1.26 Actions Features

  • Concurrency groups — GitHub-style concurrency: in workflows
  • Per-runner disable/pause — toggle via UI, no unregister needed
  • Rerun failed jobs — button in UI
  • Configurable token permissions — permissions: block in workflows
  • Non-zipped artifacts — action v7 format
  • Private repo workflows — reusable workflows from private repos
  • Workflow dependencies graph — visual dependency tree in UI

Common Mistakes

  • Stale image — gitea/act_runner is deprecated. Use gitea/runner.
  • No :host on Talos — Without Docker socket, labels must use :host suffix. Runner will fail trying to spawn containers.
  • Registration token via GET removed — v1.26 removed GET /api/v1/admin/runners/registration-token. Use UI or gitea actions generate-runner-token.
  • Cache config — cache.external_server now requires cache.external_secret (v1.0.0+). Set both or cache fails.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.