LLMScaffolding/COMMON/proposals/bootstrap-cicd.md

Bootstrap CI/CD Proposal (Phase 1)

• Scope: Local developer parity via Docker-first tooling and hooks, minimal CI placeholders (no runners required yet). Applies to this repo (docs/scripts/docker-compose), with an easy path to template for others.

Checks To Implement Now (Local via Docker)

• Stacks: shell, Dockerfiles/Compose, Markdown/Docs, YAML; Python/Node optional later.
• Formatters/Linters:
  • shell: shfmt + shellcheck
  • docker: hadolint
  • markdown: markdownlint + prettier
  • yaml: yamllint + actionlint (for workflows)
• Tests: none for now (lint-only baseline).
• Security: skip for this repo now.

Execution Model

• Docker-only: all checks run inside a pinned ci image. Host only orchestrates Docker/Compose.
• Single entrypoint: scripts/ci with phases: format, lint, build (compose validate), test (no-op for now), security (no-op), all.
• Compose file: docker/ci.compose.yml defines ci service that mounts repo and executes scripts/ci <phase>.

Hooks Parity

• Provide Git hooks via pre-commit framework and native Git hooks:
  • pre-commit: run format, lint, and commit message check (Conventional Commits).
  • pre-push: run build (compose config validation) and keep test/security as no-ops for now.
• Commit message style: Conventional Commits via commitlint rule-set; enforce in CI later and locally via commit-msg hook.

Minimal CI (Deferred Enablement)

• Workflows will be prepared but can stay disabled until runners are available:
  • .gitea/workflows/ci.yml: mirrors local lint + build using the same ci image; triggered on PRs when enabled.
  • .gitea/workflows/release.yml: on main merges, tags with vYYYY.MM.DD-HHMM and (optionally) creates release notes; can be enabled later.
  • .gitea/workflows/nightly.yml: scheduled dependency/lint refresh; optional for later.
• All jobs execute inside the ci container image; no host package installs.

Caching & Matrix

• Matrix: single Linux image for now.
• Caching: enable Docker layer cache when CI runners are available; no special local caching required.

Concurrency & Timeouts (defaults for later)

• Cancel in-progress on same ref: enabled for PRs.
• Job timeout: 30 minutes.

Protected Check Names (for later enforcement)

• ci / lint, ci / build, ci / commitlint. Tests/Security can be added when introduced.

Files To Add (upon approval)

• scripts/ci (bash) — phases and Docker/host detection (host executes Docker only).
• ci.Dockerfile — pinned versions: shfmt, shellcheck, hadolint, yamllint, markdownlint-cli, prettier, actionlint, commitlint.
• docker/ci.compose.yml — ci service to run checks.
• .pre-commit-config.yaml — wire to scripts/ci phases; enable commit-msg hook for commitlint.
• commitlint.config.cjs — Conventional Commits rules.
• .gitea/workflows/ci.yml, release.yml, nightly.yml — prepared but can be disabled until runners are ready.
• Makefile — check, quick, lint, format, build targets mapping to scripts.

Rollout Plan

1. Implement local tooling and hooks on bootstrap-cicd.
2. Document quickstart in docs/engineering/ci-cd.md.
3. Later: enable Gitea workflows when runners are ready; add protected checks.
4. Optionally expand with tests/security scanners and language stacks per repo.

If this matches your intent, I will scaffold the above on bootstrap-cicd and then capture the finalized process in COMMON/bootstrap-cicd.md.