gitea-runner-operator/specification.md

# Gitea Runner Operator Specification

## 1. Overview

The Gitea Runner Operator is a Kubernetes controller designed to manage ephemeral Gitea Act runners. It automates the provisioning of runner pods based on the demand of queued jobs in a Gitea instance. By defining `RunnerGroup` resources, users can configure pools of runners with specific scopes (global, organization, or repository) and labels.

## 2. Terminology

- **CRD**: Custom Resource Definition.
- **RunnerGroup CR**: The custom resource instance defining a runner pool.
- **Ephemeral Runner**: A runner that executes exactly one job and then terminates.
- **Gitea Instance**: The target Gitea server where CI/CD workflows are triggered.
- **Runner Capabilities**: The set of labels a runner provides (e.g., `ubuntu-latest`).
- **Job Requirements**: The set of labels a job requests (e.g., `ubuntu-latest`).

## 3. Custom Resource Definition (CRD)

### 3.1 Metadata

- **Group**: `gitea.bpg.pw`
- **Version**: `v1alpha1`
- **Kind**: `RunnerGroup`
- **Scope**: Namespaced

### 3.2 Spec Schema

The `spec` defines the configuration for the runner pool.

| Field               | Type                                   | Required    | Description                                                                                                 |
| :------------------ | :------------------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------- |
| `scope`             | Enum (`global`, `org`, `user`, `repo`) | Yes         | The scope of the runner.                                                                                    |
| `org`               | String                                 | Conditional | The organization name. Required if `scope` is `org`.                                                        |
| `user`              | String                                 | Conditional | The username. Required if `scope` is `user`.                                                                |
| `repo`              | String                                 | Conditional | The repository name. Required if `scope` is `repo`.                                                         |
| `gitea.url`         | String                                 | Yes         | The base URL of the Gitea instance (e.g., `https://gitea.example.com`).                                     |
| `labels`            | []String                               | No          | List of labels for the runner (e.g., `app:infra`). Defaults (e.g. `ubuntu-latest`) are added automatically. |
| `maxActiveRunners`  | Integer                                | Yes         | The maximum number of concurrent runner Jobs allowed for this specific RunnerGroup CR.                      |
| `registrationToken` | SecretKeySelector                      | Yes         | Reference to a Secret containing the runner registration token.                                             |
| `authToken`         | SecretKeySelector                      | Yes         | Reference to a Secret containing an API token to query Gitea for job statuses.                              |

#### 3.2.1 SecretKeySelector

Standard Kubernetes Secret reference:

- `secretRef.name`: Name of the secret.
- `secretRef.key`: Key within the secret containing the value.

### 3.3 Status Schema

- `activeRunners`: Integer. Current count of running Jobs managed by this CR.
- `lastCheckTime`: Timestamp. Last time the controller polled Gitea.

## 4. Controller Logic

### 4.1 Reconciliation Loop

The controller watches for changes to `RunnerGroup` resources.

1.  **Validation**: Ensure `org` or `repo` are present based on `scope`.
2.  **Job List**: List child Jobs to determine `activeRunners` count.
3.  **Status Update**: Update CR status with current metrics.
4.  **Capacity Check**: If `activeRunners >= maxActiveRunners`, stop scaling up.
5.  **Polling**: Fetch job statistics from Gitea.

### 4.2 Polling & Scaling Strategy

The operator uses a robust polling strategy to handle the disconnect between Kubernetes Pod startup time and Gitea's job queue state.

#### 4.2.1 Fetching Stats (`GetRunnerStats`)

The controller queries Gitea for:

1.  **Queued Jobs**: Jobs with status `queued`, `waiting`, or `pending`.
    - **Label Filtering**: Jobs are filtered client-side. A job is considered a match if the RunnerGroup's capabilities (Spec labels + Default labels) are a superset of the Job's required labels.
2.  **Running Jobs**: Jobs with status `running` that belong to this specific runner group (filtered by runner name prefix).

#### 4.2.2 Deduplication Cache (`SpawnedJobsCache`)

To prevent "double scheduling" (where multiple reconciliation loops spawn multiple runners for the same queued job before the first runner can pick it up), the controller maintains an in-memory cache:

- **Key**: Gitea Job ID.
- **Value**: Timestamp when the runner was spawned.
- **TTL**: 5 minutes.

#### 4.2.3 Scaling Algorithm

1.  **Identify Candidates**: Iterate through the list of Queued Jobs from Gitea.
2.  **Check Cache**:
    - If Job ID is in cache and TTL has not expired: **Skip** (Runner already spawned).
    - If Job ID is in cache and TTL expired: **Retry** (Runner likely failed to start).
    - If Job ID is not in cache: **Candidate for spawning**.
3.  **Calculate Slots**: `availableSlots = maxActiveRunners - activeRunners`.
4.  **Spawn**: For each candidate, if `availableSlots > 0`:
    - Create Kubernetes Job.
    - Add Job ID to `SpawnedJobsCache`.
    - Decrement `availableSlots`.
5.  **Cleanup**: Remove Job IDs from the cache if they are no longer present in the Queued Jobs list returned by Gitea (implies they are now Running, Completed, or Cancelled).

## 5. Kubernetes Resource Generation

### 5.1 Job Specification

The controller creates a `batch/v1 Job`.

**Metadata:**

- `name`: `{runnergroup-name}-{random-suffix}`
- `namespace`: Same as `RunnerGroup` CR.
- `labels`:
  - `gitea.bpg.pw/runnergroup-name`: `{runnergroup-name}`
  - `gitea.bpg.pw/managed-by`: `gitea-runner-operator`
- `ownerReferences`: Pointing to the `RunnerGroup` CR.

**Spec:**

- `ttlSecondsAfterFinished`: 600 (Auto-cleanup).
- `template`:
  - `spec`:
    - `restartPolicy`: `OnFailure`
    - `containers`:
      - **Name**: `runner`
      - **Image**: `gitea/act_runner:nightly-dind-rootless`
      - **Env**:
        - `GITEA_INSTANCE_URL`: From `spec.gitea.url`.
        - `GITEA_RUNNER_REGISTRATION_TOKEN`: From Secret.
        - `GITEA_RUNNER_EPHEMERAL`: `"true"`.
        - `GITEA_RUNNER_NAME`: `{job-name}` (Matches Pod name for easier debugging).
        - `GITEA_RUNNER_LABELS`: Comma-separated list of **Effective Labels**.
          - **Effective Labels** = `spec.labels` + Default Gitea Labels (e.g., `ubuntu-latest:docker://node:16-bullseye`, `ubuntu-22.04:...`, etc.) unless explicitly overridden.

## 6. Gitea API Interaction

- **Authentication**: Bearer token provided in `authToken`.
- **Endpoints Used**:
  - `/api/v1/repos/{owner}/{repo}/actions/jobs` (Repo scope)
  - `/api/v1/orgs/{org}/actions/jobs` (Org scope)
  - `/api/v1/users/{user}/repos` + `/api/v1/repos/{owner}/{repo}/actions/jobs` (User scope)
  - `/api/v1/admin/actions/jobs` (Global scope)
- **Label Matching**:
  - The controller implements logic to check: `Job.Labels ⊆ Runner.EffectiveLabels`.
  - Supports both exact matches (`linux`) and schema matches (`ubuntu-latest` matches `ubuntu-latest:docker://...`).

## 7. Security Considerations

- **Token Handling**: Tokens are injected via `valueFrom: secretKeyRef` env vars.
- **Privileged Mode**: `act_runner` dind mode requires privileged security context.
- **Namespace Isolation**: Controller operates within the namespace of the RunnerGroup.