0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-13 22:26:49 +00:00

Files

T

kevinveenbirkenbachandClaude Opus 4.7 4f2dd95fe9 feat(ci): add CI_RUN_ON_MAIN gate, reorg actions docs

Add repository variable CI_RUN_ON_MAIN that gates whether pushes to
main trigger CI. When unset (default), pushes to main skip CI;
set to 'true' to enable. Pushes to other branches are unaffected.

Reorganize GitHub Actions docs into a dedicated tools/github/actions/
directory and consolidate every CI repository variable in a single
SPOT (configuration.md). Move actions.md to actions/workflows.md and
branch/configuration.md to actions/configuration.md, then update
every cross-reference. Trim README files to scope-only per
docs/contributing/artefact/files/docs/readme_md.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-18 16:31:52 +02:00

5.9 KiB

Raw Blame History

Continuous Integration 🔄

This document describes the CI pipeline structure, entry points, and gates used in Infinito.Nexus. For the catalog of every workflow file (description, triggers, inputs) see workflows.md.

Overview 🗺️

CI is triggered automatically on pull request events and push to latest. The pipeline is composed of reusable workflow files under .github/workflows/. The central coordinator is ci-orchestrator.yml, which is called by the entry workflows.

Entry Points 🚪

Trigger	Workflow	Description
Pull request (opened, synchronize, reopened, ready_for_review)	entry-pull-request-change.yml	Detects PR scope and conditionally runs the full orchestrator
Push to `latest`	entry-push-latest.yml	Runs the full orchestrator on the main branch
Manual dispatch	entry-manual.yml	Allows triggering CI for a specific role or whitelist

PR Scope Detection 🔎

Before the full pipeline runs, CI detects the scope of the PR based on the changed files and the branch prefix (see branch.md).

Documentation-only and agent-only PRs MUST pass a lightweight gate without running the full orchestrator.
All other scopes MUST run the full ci-orchestrator.yml.
The branch prefix MUST match the detected scope, otherwise the validate-pr-branch-prefix job fails.

Pipeline Stages 🏗️

The orchestrator runs the following stages in order:

1. Fork Prerequisites ⏳

For fork PRs, CI waits for privileged images to be built by the pull_request_target event before proceeding. This ensures untrusted code never runs with elevated permissions.

2. Security 🛡️

security-codeql.yml: Static analysis via GitHub CodeQL.

3. Linting 🧹

All linting jobs run in parallel:

All four MUST pass the lint-gate before the pipeline continues.

4. CI Image Build 🐳

images-build-ci.yml builds Docker images for the target distributions (arch, debian, ubuntu, fedora, centos). These images are used by all subsequent test jobs.

5. Code Tests 🧪

Run in parallel after images are available:

All three MUST pass the test-code-gate.

6. Code Quality Gate 🚦

The code-quality-gate requires linting, code tests, and security checks to all pass before deploy tests are triggered.

7. DNS Tests 🌐

test-dns.yml validates DNS configuration across all target distributions.

8. Image Mirroring 🪞

images-mirror-missing.yml mirrors any missing upstream images in parallel with the DNS tests so later deploy jobs pull from GHCR instead of Docker Hub, MCR, or other external registries. This shields CI from upstream rate limits, geo-blocking, and transient registry outages.

Fork PRs cannot publish mirror packages directly, so their untrusted runs wait for the trusted mirror producer before continuing. See mirror.md for the mirroring architecture and naming convention.

GHCR publication uses the workflow GITHUB_TOKEN; optional Docker Hub secrets are used only to reduce source-side Docker Hub rate limits while mirroring. See authentication.md.

9. Deploy Tests 🚀

Run in parallel after DNS and mirroring:

test-deploy-server.yml: Server and web-* roles.
test-deploy-universal.yml: Shared system roles.
test-deploy-workstation.yml: Workstation and desk-* roles.

10. Installation Tests 📦

Run in parallel after the code quality gate:

Both MUST pass the test-install-gate.

11. Development Environment 🛠️

test-environment.yml validates the development environment setup.

12. Done 🏁

The final done job aggregates all deploy, install, and development gates. CI is considered green only when this job succeeds.

Concurrency 🔀

PR pipelines use cancel-in-progress: true so only the newest run per PR and event type is active.
The orchestrator uses cancel-in-progress: false to avoid interrupting long-running deploy tests mid-flight.
The push entry workflow (entry-push-latest.yml) defaults to cancel-in-progress: true but respects the repository variable CI_CANCEL_IN_PROGRESS.

See configuration.md for all repository variables that control CI behaviour.

Fork PRs 🍴

Fork PRs run under the pull_request event without write permissions. Privileged steps (image builds, package writes) run via pull_request_target after a maintainer review. The fork CI waits for those privileged images before proceeding. See pull-request.md for the contributor-facing fork workflow.

5.9 KiB Raw Blame History