computer-playbook/docs/contributing/tools/github/actions/configuration.md

# CI Configuration ⚙️

This page lists every repository variable that controls GitHub Actions CI behaviour in this repo. For the workflow catalog see [workflows.md](workflows.md); for the CI flow see [pipeline.md](../../../artefact/git/pipeline.md).

Repository variables are set under **Settings → Secrets and variables → Actions → Variables**.

## Variables 📋

| Variable | Workflow | Default (unset) | Set to activate |
|---|---|---|---|
| `CI_CANCEL_IN_PROGRESS` | [entry-push-latest.yml](../../../../../.github/workflows/entry-push-latest.yml), [call-orchestrator.yml](../../../../../.github/workflows/call-orchestrator.yml) | Cancels in-progress runs on new push | `false` to keep in-progress runs alive |
| `CI_SYNC_MAIN_SOURCE_REPOSITORY` | [entry-push-latest.yml](../../../../../.github/workflows/entry-push-latest.yml) | Syncs `main` from `infinito-nexus/core` before CI scope discovery | `<owner>/<repo>` to use another source, or `false`, empty, or the current repository to skip |
| `CI_RUN_ON_MAIN` | [entry-push-latest.yml](../../../../../.github/workflows/entry-push-latest.yml) | Pushes to `main` skip CI | `true` to run CI on `main` pushes too |
| `CI_ENABLE_AUTO_UPDATES` | [cron-update.yml](../../../../../.github/workflows/cron-update.yml), [entry-pr-open-dependabot-close.yml](../../../../../.github/workflows/entry-pr-open-dependabot-close.yml) | Update jobs skipped; Dependabot PRs auto-closed | `true` to allow update PRs (workflow-driven and Dependabot) |
| `INFINITO_PLAYWRIGHT_KEEP` | [call-test-deploy-compose.yml](../../../../../.github/workflows/call-test-deploy-compose.yml) | Playwright keeps trace, screenshot and video only when a test fails | `true` to keep them for every test (passing runs included) |
| `CI_RERUN_INTERVAL_MINUTES` | [cron-rerun-cancelled.yml](../../../../../.github/workflows/cron-rerun-cancelled.yml) | Sweeps for cancelled runs every full hour | Minutes between two sweeps, rounded up to whole hours |
| `CI_RERUN_MAX_ATTEMPTS` | [cron-rerun-cancelled.yml](../../../../../.github/workflows/cron-rerun-cancelled.yml) | Revives a run however often it is cancelled | Attempt count at which a run is left alone; `0` for no ceiling |
| `CI_RERUN_MAX_AGE_HOURS` | [cron-rerun-cancelled.yml](../../../../../.github/workflows/cron-rerun-cancelled.yml) | Ignores runs untouched for more than 24 hours | Age in hours beyond which a cancelled run is left alone |

## `CI_CANCEL_IN_PROGRESS` 🛑

Controls whether a new run cancels an already-running CI pipeline on the same ref. Applies to the push entry workflow and to the orchestrator's own concurrency group, which every entry workflow shares. The manual entry workflow overrides the variable on both levels: its own group is `cancel-in-progress: true`, and it passes `force_cancel_in_progress: true` into the orchestrator.

**Default behaviour (variable not set or set to any value other than `false`):**
In-progress runs are cancelled when a new push arrives. This is the recommended setting for most workflows.

**To disable cancellation:**

1. Open the repository on GitHub.
2. Go to **Settings → Secrets and variables → Actions**.
3. Switch to the **Variables** tab.
4. Click **New repository variable**.
5. Set **Name** to `CI_CANCEL_IN_PROGRESS` and **Value** to `false`.
6. Save.

**To re-enable cancellation:**

Delete the variable or change its value to anything other than `false` (e.g. `true`).

**How it works:**

```yaml
cancel-in-progress: ${{ vars.CI_CANCEL_IN_PROGRESS != 'false' }}
```

| Variable value | Expression result | Behaviour |
|---|---|---|
| *(not set / empty)* | `'' != 'false'` → `true` | Cancels in-progress runs ✓ |
| `false` | `'false' != 'false'` → `false` | Does **not** cancel ✓ |
| `true` | `'true' != 'false'` → `true` | Cancels in-progress runs ✓ |

## `CI_SYNC_MAIN_SOURCE_REPOSITORY` 🔄

Controls whether the push workflow updates the current repository's `main` branch before any later job derives deploy scope from `origin/main`.
This keeps fork branch pushes aligned with the canonical default branch so diff-driven role discovery sees only the branch's own changes.

> ⚠️ **Forced overwrite — do not work in `main`.**
> When the sync runs, the current repository's `main` is **force-pushed** from the source repository's `main`. Any commit that exists only on the fork's `main` is **discarded without warning** on the next push to any covered branch.
> Never commit or merge work directly into `main` on a synced repository. Always work on a `feature/**`, `fix/**`, or `hotfix/**` branch; treat `main` as a read-only mirror of the source.
> If you must use `main` as a working branch, disable the sync first (see **To disable the sync** below).

**Default behaviour (variable not set):**
The workflow uses `infinito-nexus/core` as the source repository.
When the current repository is already `infinito-nexus/core`, the same-repository skip applies.

**To use a different source repository:**

1. Open the repository on GitHub.
2. Go to **Settings → Secrets and variables → Actions**.
3. Switch to the **Variables** tab.
4. Click **New repository variable**.
5. Set **Name** to `CI_SYNC_MAIN_SOURCE_REPOSITORY` and **Value** to `<owner>/<repo>`.
6. Save.

**To disable the sync:**

Set the variable to `false`, `0`, `no`, `off`, `none`, an empty value, or the current repository name.

| Variable value | Behaviour |
|---|---|
| *(not set)* | Uses `infinito-nexus/core`; syncs forks and skips in `infinito-nexus/core` itself ✓ |
| `infinito-nexus/core` in a fork | Syncs the fork's `main` from `infinito-nexus/core` ✓ |
| current repository | Sync skipped ✓ |
| `false`, `0`, `no`, `off`, `none`, or empty | Sync skipped ✓ |

## `CI_RUN_ON_MAIN` 🎯

Controls whether pushes to `main` trigger the CI pipeline. Pushes to all other branches covered by the workflow (`feature/**`, `hotfix/**`, `fix/**`, `alert-autofix-*`) are unaffected.

**Default behaviour (variable not set or set to any value other than `true`):**
Pushes to `main` are gated out at the `run-policy` job and CI is skipped.

**To enable CI on `main` pushes:**

1. Open the repository on GitHub.
2. Go to **Settings → Secrets and variables → Actions**.
3. Switch to the **Variables** tab.
4. Click **New repository variable**.
5. Set **Name** to `CI_RUN_ON_MAIN` and **Value** to `true`.
6. Save.

**To disable again:**

Delete the variable or change its value to anything other than `true`.

**How it works:**

The gate is applied inside [push_ci_policy.sh](../../../../../scripts/meta/resolve/push_ci_policy.sh), which the `run-policy` job invokes. When `GITHUB_REF == refs/heads/main` and `CI_RUN_ON_MAIN != 'true'`, the job emits `should_run=false` and every downstream job is skipped.

| Variable value | Ref is `main` | Behaviour |
|---|---|---|
| *(not set / empty)* | yes | CI skipped ✓ |
| `true` | yes | CI runs ✓ |
| any other value | yes | CI skipped ✓ |
| *(any)* | no | Unaffected (CI runs per branch rules) ✓ |

## `CI_ENABLE_AUTO_UPDATES` 🔄

Controls whether automated update PRs are created. Covers both the workflow-driven jobs in [cron-update.yml](../../../../../.github/workflows/cron-update.yml) (Docker image versions, agent skills) and PRs opened by Dependabot (gated via [entry-pr-open-dependabot-close.yml](../../../../../.github/workflows/entry-pr-open-dependabot-close.yml), which auto-closes them).

The workflow-driven jobs additionally require the `BOT_APP_CLIENT_ID` and `BOT_APP_PRIVATE_KEY` repository secrets, see [secrets.md](secrets.md). Without those secrets, runs fail at the token-minting step and no PR is opened.

**Default behaviour (variable not set or set to any value other than `true`):**
The `update-docker-image-versions` job is skipped. Dependabot PRs are auto-closed on open with a comment pointing to this variable.

**To enable update PRs:**

1. Open the repository on GitHub.
2. Go to **Settings → Secrets and variables → Actions**.
3. Switch to the **Variables** tab.
4. Click **New repository variable**.
5. Set **Name** to `CI_ENABLE_AUTO_UPDATES` and **Value** to `true`.
6. Save.

**To disable again:**

Delete the variable or change its value to anything other than `true`.

**How it works:**

In [cron-update.yml](../../../../../.github/workflows/cron-update.yml) each job carries a job-level guard:

```yaml
if: vars.CI_ENABLE_AUTO_UPDATES == 'true'
```

Dependabot cannot read repository variables itself, so [entry-pr-open-dependabot-close.yml](../../../../../.github/workflows/entry-pr-open-dependabot-close.yml) listens on `pull_request_target` (`opened`, `reopened`) and closes any PR authored by `dependabot[bot]` while `CI_ENABLE_AUTO_UPDATES != 'true'`. The workflow does not check out PR code, which keeps the elevated `pull_request_target` context safe.

| Variable value | Workflow update jobs | Dependabot PRs |
|---|---|---|
| *(not set / empty)* | Skipped ✓ | Auto-closed on open ✓ |
| `true` | Run ✓ | Stay open ✓ |
| any other value | Skipped ✓ | Auto-closed on open ✓ |

## `INFINITO_PLAYWRIGHT_KEEP` 🎬

Controls whether Playwright keeps trace, screenshot, and video for every test or only for failing tests in the compose deploy-test workflow ([call-test-deploy-compose.yml](../../../../../.github/workflows/call-test-deploy-compose.yml)).
For the full propagation chain, the inventory override, and the local equivalents, see [Playwright Tests](../../../actions/testing/playwright.md#artefact-retention-).

**Default behaviour (variable not set or set to any value other than `true`):**
Artefacts are retained only when a test fails.

**To retain artefacts for every test:**

1. Open the repository on GitHub.
2. Go to **Settings → Secrets and variables → Actions**.
3. Switch to the **Variables** tab.
4. Click **New repository variable**.
5. Set **Name** to `INFINITO_PLAYWRIGHT_KEEP` and **Value** to `true`.
6. Save.

**To disable again:**

Delete the variable or change its value to anything other than `true`.

**How it works:**

Each deploy-test workflow forwards the variable into its own `env:` block:

```yaml
INFINITO_PLAYWRIGHT_KEEP: ${{ vars.INFINITO_PLAYWRIGHT_KEEP }}
```

| Variable value | Behaviour |
|---|---|
| *(not set / empty)* | Trace / screenshot / video kept only on failure ✓ |
| `true` | Trace / screenshot / video kept for every test ✓ |
| any other value | Trace / screenshot / video kept only on failure ✓ |

## `CI_RERUN_*` 🔁

Three variables tune [cron-rerun-cancelled.yml](../../../../../.github/workflows/cron-rerun-cancelled.yml), the sweep that restarts the failed jobs of a branch whose latest run was cancelled.

| Variable | Unset | Effect when set |
|---|---|---|
| `CI_RERUN_INTERVAL_MINUTES` | `60` | Minutes between two sweeps |
| `CI_RERUN_MAX_ATTEMPTS` | `0` | A run at or above this attempt count is left alone; `0` means no ceiling, a run is revived however often it is cancelled |
| `CI_RERUN_MAX_AGE_HOURS` | `24` | A run untouched for longer than this is left alone, so a sweep does not resurrect abandoned branches |

**How the interval works:**

A cron expression cannot read a repository variable, so the workflow is triggered every full hour and a gate lets only the hours that open the configured window through:

```yaml
INTERVAL_MINUTES: ${{ vars.CI_RERUN_INTERVAL_MINUTES || '60' }}
```

The interval is rounded up to whole hours and counted from 00:00 UTC, so `60` sweeps every hour, `180` at 00:00, 03:00, 06:00 and so on, and `1440` once a day at 00:00. One hour is the floor: anything below it sweeps hourly. Anything above 24 hours collapses to a daily sweep. Manual dispatch skips the gate entirely and always sweeps.

The gate reads the hour, not the minute, so a scheduled run that GitHub starts a few minutes late still counts for its hour.

**On the missing ceiling:** with `CI_RERUN_MAX_ATTEMPTS` unset, a run that is cancelled again after every revival is revived again, indefinitely. `CI_RERUN_MAX_AGE_HOURS` does not bound this, because each new attempt refreshes the run's `updatedAt` and so keeps it inside the age window. Set the variable to a positive number if a run should eventually be given up on.