# Configuration Reference — ${REPO_NAME}

All settings live in **`.ci/config.env`** and are loaded by every workflow at runtime.

## CI Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_CI` | `true` | Master switch. If `false`, the CI workflow exits immediately. |
| `CI_STRICT` | `true` | If `true`, lint/test failures cause the workflow to fail. If `false`, they are logged as warnings only. |
| `DEFAULT_BRANCH` | `main` | The primary branch. Used by Docker and other workflows to determine branch-push behavior. |

## Docker Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_DOCKER` | `true` | Master switch for Docker build steps. |
| `DOCKER_PUSH` | `false` | Whether to push images to the registry. **Safe default: off.** |
| `DOCKER_PUSH_ON_BRANCH` | `true` | Push when a commit lands on `DEFAULT_BRANCH`. Only effective if `DOCKER_PUSH=true`. |
| `DOCKER_PUSH_ON_TAG` | `true` | Push when a semver tag (`v*`) is pushed. Only effective if `DOCKER_PUSH=true`. |
| `REGISTRY_HOST` | `git.hiddenden.cafe` | Hostname of the container registry. |
| `IMAGE_OWNER` | `auto` | Image owner (org/user). `auto` = derived from repository context at runtime. |
| `IMAGE_NAME` | `auto` | Image name. `auto` = derived from repository name at runtime. |
| `DOCKER_TAG_STRATEGY` | `semver+latest` | Controls tagging. Options: `semver+latest`, `semver`, `branch`. |

### Tag Strategy Details

| Trigger | `semver+latest` | `semver` | `branch` |
|---------|-----------------|----------|----------|
| `v1.2.3` tag | `:1.2.3` + `:latest` | `:1.2.3` | — |
| Push to `main` | `:main` | `:main` | `:main` |
| Pull request | `:pr-<N>` (local only) | `:pr-<N>` (local only) | `:pr-<N>` (local only) |

## Security Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_SECURITY` | `false` | Master switch. Enables gitleaks, osv-scanner, and Trivy. |
| `STRICT_SECURITY` | `false` | If `true`, any finding fails the workflow. If `false`, findings are warnings. |

## Renovate Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_RENOVATE` | `false` | Master switch for Renovate dependency updates. |
| `RENOVATE_SCHEDULE` | `weekly` | How often Renovate runs. |
| `RENOVATE_PR_LIMIT` | `5` | Max open PRs Renovate can create. |

## Deploy Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_DEPLOY` | `false` | Master switch. Deploy never runs unless `true`. |
| `DEPLOY_MODE` | `local-runner` | How to reach the VPS: `local-runner` (runs on VPS directly) or `ssh` (SSH from any runner). |
| `DEPLOY_RUNNER_LABEL` | `deploy-ovh` | Runner label for local-runner mode. Must match the act_runner's registered label. |
| `DEPLOY_WORKDIR` | `/opt/${REPO_NAME}` | Working directory on the VPS where your project lives. |
| `DEPLOY_STRATEGY` | `compose` | What to do on deploy: `compose` (docker compose up), `systemd` (restart service), or `script` (run custom script). |
| `DEPLOY_COMPOSE_FILE` | `docker-compose.yml` | Compose file path relative to `DEPLOY_WORKDIR`. Used with `compose` strategy. |
| `DEPLOY_SYSTEMD_SERVICE` | _(empty)_ | Systemd service name. Required if `DEPLOY_STRATEGY=systemd`. |
| `DEPLOY_SCRIPT` | `scripts/deploy.sh` | Custom deploy script path relative to repo root. Used with `script` strategy. |
| `DEPLOY_ON_TAG` | `false` | Also deploy when a `v*` tag is pushed. |

### Deploy Mode Comparison

| | `local-runner` | `ssh` |
|---|---|---|
| Secrets needed | None | `DEPLOY_SSH_KEY`, `DEPLOY_HOST`, `DEPLOY_USER` |
| Runner location | On the VPS | Any runner (e.g., shared) |
| Setup effort | Install act_runner on VPS | Create SSH key + add secrets |
| Network exposure | None | SSH port must be reachable |

See [docs/DEPLOY.md](DEPLOY.md) for full setup instructions.

## Recommended Defaults

For a **new public project**:
```env
ENABLE_CI=true
CI_STRICT=true
ENABLE_DOCKER=true
DOCKER_PUSH=false          # Enable when ready to publish
ENABLE_SECURITY=false      # Enable after initial development
ENABLE_RENOVATE=false      # Enable after first release
ENABLE_DEPLOY=false        # Enable when VPS runner is set up
```

For a **production project**:
```env
ENABLE_CI=true
CI_STRICT=true
ENABLE_DOCKER=true
DOCKER_PUSH=true
DOCKER_PUSH_ON_TAG=true
ENABLE_SECURITY=true
STRICT_SECURITY=true
ENABLE_RENOVATE=true
ENABLE_DEPLOY=true
DEPLOY_MODE=local-runner
DEPLOY_STRATEGY=compose
```