69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
**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](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](COMMON/bootstrap-cicd.md).
|