gitea-runner

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

```bash
# 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

```bash
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

| Mode | Description | Docker Required |
|------|-------------|----------------|
| **Host** | Steps run directly on host process | No |
| **Docker** | Steps in sibling containers via socket | Yes (`/var/run/docker.sock`) |
| **DinD** | Rootless, own Docker daemon in container | Yes (privileged container) |

### Kubernetes / Talos (Host Mode)

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

```yaml
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

```bash
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.

From Aidas-dev/k8s-agent-skills, MIT.

More from Aidas-dev/k8s-agent-skills