@ebalzan/ci 0.0.0-stage → 3.0.0

package/docs/REPO_RULES.md

@@ -0,0 +1,116 @@
+# Repository settings and branch rulesets
+
+The workflows enforce the flow inside CI. These two files enforce it on GitHub
+itself, the same way on every repo: `ebalzan-ci bootstrap` applies them
+alongside the variables and secrets.
+
+```text
+config/repo-settings.json          +  <repo>/.github/repo-settings.json       → PATCH /repos/{repo}
+config/rulesets/<file>.json        +  <repo>/.github/rulesets/<file>.json     → repo rulesets, matched by "name"
+        shared                               repo (deep-merged over it, wins)
+```
+
+Both are plain GitHub REST payloads, so anything the API accepts can go in
+them. Keys starting with `$` (like `"$comment"`) are documentation and are
+never sent.
+
+---
+
+## Repository settings
+
+`config/repo-settings.json`:
+
+| Setting                       | Value             | Why                                                                                                                                                                 |
+| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allow_squash_merge`          | `true`            | The only merge method. One PR = one commit = one Conventional Commit on the target branch.                                                                          |
+| `allow_merge_commit`          | `false`           | A merge commit is not a Conventional Commit, and it would carry unrelated history into `main`.                                                                      |
+| `allow_rebase_merge`          | `false`           | Replays every branch commit; each would need to be conventional, and the PR title would not be the subject.                                                         |
+| `squash_merge_commit_title`   | `PR_TITLE`        | **Important.** GitHub's default (`COMMIT_OR_PR_TITLE`) uses the _commit_ subject for a single-commit PR, bypassing the PR-title check that guards the release bump. |
+| `squash_merge_commit_message` | `COMMIT_MESSAGES` | The branch's commit messages go in the body, so a `BREAKING CHANGE:` footer still reaches the release scan.                                                         |
+| `delete_branch_on_merge`      | `true`            | Work branches are short-lived; the tracking issue keeps the history.                                                                                                |
+| `allow_update_branch`         | `true`            | Offers "Update branch" on PRs that fall behind `dev`.                                                                                                               |
+
+`bootstrap --dry-run` lists only the keys whose current value differs:
+
+```text
+==> Repository settings to change
+    allow_rebase_merge             true → false
+    squash_merge_commit_title      "COMMIT_OR_PR_TITLE" → "PR_TITLE"
+```
+
+To change one for a single repo, put just that key in its
+`.github/repo-settings.json`:
+
+```json
+{ "delete_branch_on_merge": false }
+```
+
+---
+
+## Branch rulesets
+
+| File                        | Ruleset name               | Default      | Rules                                                                                      |
+| --------------------------- | -------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
+| `protect-main.json`         | `ci: protect main`         | **active**   | `main` cannot be deleted or force-pushed.                                                  |
+| `protect-dev.json`          | `ci: protect dev`          | **active**   | `dev` cannot be deleted.                                                                   |
+| `require-pull-request.json` | `ci: require pull request` | **disabled** | Changes to `main`/`dev` only by squash-merged PR with `title / Validate PR Title` passing. |
+
+### Why `dev` can still be force-pushed
+
+`release.yml`'s `sync-dev` job force-points `dev` at every release commit (the
+squash merge into `main` leaves `dev` with the same content under unrelated
+history; see [CI_FLOW.md §4](CI_FLOW.md#4-version-bump-rules-commit-scan)). A
+`non_fast_forward` rule on `dev` would break every release. The test suite
+fails if an active ruleset adds one.
+
+### Why "require pull request" ships disabled
+
+The release job pushes the `chore(release): X.Y.Z` commit straight to `main`
+and force-points `dev`, both as `github-actions[bot]` (`GITHUB_TOKEN`). With
+PRs required, those pushes need a bypass. The ruleset lists two bypass actors:
+
+| Actor                        | Id      | Why                              |
+| ---------------------------- | ------- | -------------------------------- |
+| `RepositoryRole` admin       | `5`     | You, for emergencies.            |
+| `Integration` GitHub Actions | `15368` | The release and sync-dev pushes. |
+
+Whether GitHub honours the GitHub Actions app as a bypass actor depends on the
+account type and plan, so it is off until you have seen it work. To turn it on
+for one repo:
+
+```bash
+mkdir -p .github/rulesets
+echo '{ "enforcement": "active" }' > .github/rulesets/require-pull-request.json
+ebalzan-ci bootstrap --skip vars,secrets
+```
+
+Then merge a promotion PR and check that the release run pushed its commit and
+synced `dev`. If it was rejected, set the file back to `"disabled"` and
+re-run the bootstrap. Once it works on your setup, flip `enforcement` in
+`config/rulesets/require-pull-request.json` itself to roll it out everywhere.
+
+### Plans
+
+Rulesets are free on **public** repos. On **private** repos they need GitHub
+Pro (personal accounts) or Team (organizations); otherwise GitHub answers
+"Upgrade to GitHub Pro or make this repository public" and `bootstrap` warns
+and skips the step, leaving the rest of the sync intact.
+
+### Adding, overriding, removing
+
+- **Override** a shared ruleset in one repo: a file with the **same file name**
+  in `.github/rulesets/`, containing only the keys to change. Arrays (such as
+  `rules` or `conditions.ref_name.include`) are replaced whole.
+- **Add** a ruleset to one repo: any new file name in `.github/rulesets/`. Give
+  it a `"name"` starting with `ci: ` if you want `--prune` to manage it.
+- **Add** one for every repo: a new file in `config/rulesets/`, then a release.
+- **Remove** a shared one from one repo: override it with
+  `{ "enforcement": "disabled" }`.
+- **Delete** one everywhere: remove its file, then `ebalzan-ci bootstrap --all
+--prune`. Pruning only ever deletes repo rulesets whose name starts with
+  `ci: `; rulesets you made by hand under other names are never touched.
+
+Rulesets are matched to GitHub by `name`: renaming one in a file creates a new
+ruleset and leaves the old one until `--prune`.
+
+Reference for the payload: [GitHub REST — repository rulesets](https://docs.github.com/en/rest/repos/rules).

package/managed/scripts/release/validate-conventional-subject.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env sh
+#
+# MANAGED BY ebalzan/ci (managed/scripts/release/validate-conventional-subject.sh).
+# Run it through the CLI (`ebalzan-ci commit-msg`) rather than copying it. If a
+# repo still keeps a copy, do not edit it: change it in ebalzan/ci, then run
+# `ebalzan-ci sync-managed --all`. PR Checks fails while a repo's copy differs.
+#
+# The one Conventional Commits rule, used by the husky commit-msg hook (locally,
+# via `ebalzan-ci commit-msg`) and by the shared PR-title check (in CI). The
+# allowed types must match branchReleaseTypes in scripts/release/release-utils.mjs
+# and TYPE_CONFIG in actions/auto-work-items/src/config.ts.
+set -eu
+
+subject="${1-}"
+label="${2-commit message}"
+commit_regex='^(feat|fix|docs|style|refact|perf|test|build|ci|chore|revert)(\([^)]+\))?(!)?: .+'
+
+if [ -z "$subject" ]; then
+  echo "Invalid $label: value is empty."
+  echo "Use Conventional Commits, for example:"
+  echo "  feat(viewer): add section filters"
+  echo "  fix: prevent null model crash"
+  exit 1
+fi
+
+printf '%s\n' "$subject" | grep -qE "$commit_regex" && exit 0
+
+echo "Invalid $label: \"$subject\""
+echo "Use Conventional Commits, for example:"
+echo "  feat(viewer): add section filters"
+echo "  fix: prevent null model crash"
+exit 1

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@ebalzan/ci",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.0.0",
+  "description": "One set of CI/CD rules for all your GitHub repos: reusable workflows (Conventional Commits, auto issue/PR, semver releases), a CLI that syncs Actions config, repo settings and branch rulesets, and a commit-msg hook.",
+  "keywords": [
+    "github-actions",
+    "reusable-workflows",
+    "ci",
+    "cd",
+    "conventional-commits",
+    "semantic-release",
+    "semver",
+    "rulesets",
+    "husky",
+    "commit-msg",
+    "renovate-preset",
+    "devops"
+  ],
+  "homepage": "https://github.com/ebalzan/ci#readme",
+  "bugs": {
+    "url": "https://github.com/ebalzan/ci/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ebalzan/ci.git"
+  },
+  "license": "MIT",
+  "author": "ebalzan",
+  "type": "module",
+  "bin": {
+    "ebalzan-ci": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "managed/",
+    "templates/",
+    "renovate/",
+    "docs/",
+    "config/actions.env",
+    "config/repos.env",
+    "config/repo-settings.json",
+    "config/rulesets/",
+    "config/secrets.env.example"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p actions/auto-work-items/tsconfig.json",
+    "check": "npm run build && git diff --exit-code -- actions/auto-work-items/dist && bash -n bin/*.sh managed/scripts/release/*.sh && node --check bin/cli.mjs && node --check bin/_json.mjs && node --check scripts/release/*.mjs",
+    "test": "node --test 'test/*.test.mjs'",
+    "gh:bootstrap": "bash bin/gh-bootstrap.sh",
+    "gh:reset": "bash bin/gh-reset.sh",
+    "sync-managed": "bash bin/sync-managed.sh",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@ebalzan/config": "0.1.0",
+    "@types/node": "25.6.2",
+    "prettier": "3.9.10",
+    "typescript": "6.0.3"
+  },
+  "prettier": "@ebalzan/config/prettier"
+}

package/renovate/tooling.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "description": "Shared Renovate preset: keeps the lint, format, git-hook and compiler tooling on the same versions in every repo that extends it as github>ebalzan/ci//renovate/tooling#v2. Only the packages listed below are managed; every other dependency is left alone.",
+  "extends": ["config:recommended"],
+  "baseBranchPatterns": ["dev"],
+  "branchPrefix": "chore/renovate-",
+  "semanticCommits": "enabled",
+  "semanticCommitType": "chore",
+  "semanticCommitScope": "deps",
+  "rangeStrategy": "pin",
+  "minimumReleaseAge": "3 days",
+  "schedule": ["before 9am on monday"],
+  "dependencyDashboard": true,
+  "packageRules": [
+    {
+      "description": "Only the shared tooling below is managed; every other dependency (framework, runtime, GitHub Actions) stays manual.",
+      "matchPackageNames": ["*"],
+      "enabled": false
+    },
+    {
+      "description": "One PR per repo for the shared tooling, including the two @ebalzan packages (majors get their own PR). chore keeps the branch type and the PR title in step for pr-title.",
+      "matchPackageNames": [
+        "prettier",
+        "eslint",
+        "@eslint/js",
+        "eslint-config-prettier",
+        "eslint-plugin-prettier",
+        "typescript-eslint",
+        "lint-staged",
+        "husky",
+        "typescript",
+        "@ebalzan/config",
+        "@ebalzan/ci"
+      ],
+      "groupName": "dev tooling",
+      "semanticCommitType": "chore",
+      "enabled": true
+    },
+    {
+      "description": "typescript-eslint (used directly, or through eslint-config-next / eslint-config-expo) only supports typescript <6.1. Raise this once it does.",
+      "matchPackageNames": ["typescript"],
+      "allowedVersions": "<6.1"
+    }
+  ]
+}

package/templates/.github/actions.env

@@ -0,0 +1,17 @@
+# GitHub Actions VARIABLES specific to THIS repo. Non-sensitive; committed.
+#
+# The shared defaults (describe model, size/estimate maps, …) live in
+# __CI_REPO__'s config/actions.env and are read at run time — they are not
+# pushed here. `ebalzan-ci bootstrap` pushes this file as repository variables;
+# a key set here overrides the shared one. Every key: __CI_REPO__
+# docs/CONFIGURATION.md.
+#
+# Removing a line does not delete the variable on GitHub; run
+# `ebalzan-ci bootstrap --prune`.
+
+# This repo's Projects (v2) board number (owned by the repo owner unless
+# AUTO_PROJECT_OWNER says otherwise). Leave unset to run without a board.
+# AUTO_PROJECT_NUMBER=
+
+# Milestone put on every work item and promotion PR (exact title, open).
+# AUTO_MILESTONE_TITLE=

package/templates/.github/workflows/auto-pr.yml

@@ -0,0 +1,33 @@
+# =============================================================================
+# Auto Create Work Items — thin caller of __CI_REPO__'s shared workflow.
+#
+# On every push to a work branch (feat/…, fix/…, …) it creates or updates the
+# tracking issue, the PR into dev and, when AUTO_PROJECT_NUMBER is set, the
+# Projects (v2) card. Generated by `ebalzan-ci onboard`; the logic lives in
+# __CI_REPO__ (docs/AUTO_WORK_ITEMS_WORKFLOW.md), so this file only holds what
+# cannot live there: the trigger, the permissions and the secrets.
+# =============================================================================
+name: Auto Create Work Items
+
+on:
+  push:
+    branches-ignore:
+      - main
+      - dev
+    tags-ignore:
+      - '**'
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  repository-projects: write
+
+jobs:
+  work-items:
+    uses: __CI_REPO__/.github/workflows/auto-work-items.yml@__CI_REF__
+    with:
+      runs-on: __RUNS_ON__
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      GH_PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/templates/.github/workflows/pr-checks.yml

@@ -0,0 +1,48 @@
+# =============================================================================
+# PR Checks — the quality gate for every PR into dev or main.
+#
+#   title   The shared PR-title check (__CI_REPO__): the title must be a
+#           Conventional Commit whose type matches the branch prefix. Keep the
+#           job id `title`: the check is reported as `title / Validate PR Title`,
+#           the name the shared rulesets require.
+#
+# Add this repo's own build/test/lint jobs below; they run in parallel.
+# Generated by `ebalzan-ci onboard`.
+# =============================================================================
+name: PR Checks
+
+on:
+  pull_request:
+    branches: ['main', 'dev']
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: pr-checks-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  title:
+    uses: __CI_REPO__/.github/workflows/pr-title.yml@__CI_REF__
+    with:
+      runs-on: __RUNS_ON__
+
+  # A Node repo's own checks. Uncomment and adapt; other stacks replace the
+  # steps (e.g. `go test ./...`).
+  # validate:
+  #   name: Validate
+  #   runs-on: __RUNS_ON__
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-node@v4
+  #       with:
+  #         node-version: 24
+  #         cache: npm
+  #     - run: npm ci
+  #     # Prettier/ESLint/TypeScript extend @ebalzan/config instead of copying it.
+  #     - run: npx --no-install ebalzan-config verify
+  #     # The repo's own script: format:check, lint, typecheck, test, …
+  #     - run: npm run validate

package/templates/.github/workflows/promote-dev-to-main.yml

@@ -0,0 +1,26 @@
+# =============================================================================
+# Promote dev → main — keeps ONE evergreen dev → main PR open.
+#
+# Every push to dev opens or updates it, titled with the release it will cut
+# (e.g. `feat: promote dev to main (v1.4.0)`). Merging it (squash) is the
+# release approval. Generated by `ebalzan-ci onboard`; logic in __CI_REPO__.
+# =============================================================================
+name: Promote dev to main
+
+on:
+  push:
+    branches: ['dev']
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  promote:
+    uses: __CI_REPO__/.github/workflows/promote-dev-to-main.yml@__CI_REF__
+    with:
+      runs-on: __RUNS_ON__
+    secrets:
+      GH_PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/templates/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+# =============================================================================
+# Release — every push to main becomes a versioned release.
+#
+# The shared job computes the next semver from the Conventional Commits since
+# the last tag, bumps package.json when there is one, tags vX.Y.Z, creates the
+# GitHub Release and points dev at the release commit. Generated by
+# `ebalzan-ci onboard`; logic in __CI_REPO__ (docs/CI_FLOW.md).
+#
+# Shipping is this repo's business: chain jobs on the outputs. `tag` is empty
+# when nothing was released (the release commit's own run).
+# =============================================================================
+name: Release
+
+on:
+  push:
+    branches: ['main']
+
+permissions:
+  contents: write
+  pull-requests: read
+
+jobs:
+  release:
+    uses: __CI_REPO__/.github/workflows/release.yml@__CI_REF__
+    with:
+      runs-on: __RUNS_ON__
+
+  # deploy:
+  #   needs: release
+  #   if: ${{ needs.release.outputs.tag != '' }}
+  #   runs-on: __RUNS_ON__
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #       with:
+  #         ref: ${{ needs.release.outputs.tag }}
+  #     - run: echo "ship ${{ needs.release.outputs.tag }}"

package/templates/.husky/commit-msg

@@ -0,0 +1,18 @@
+# Conventional Commits check for every local commit, from __CI_PACKAGE__
+# (generated by `ebalzan-ci onboard`). The same rule runs on every PR title in
+# CI, so a missing package only loses the early local warning — never the check.
+
+# 1. The package, as a devDependency of this repo.
+if [ -x node_modules/.bin/ebalzan-ci ]; then
+  exec node_modules/.bin/ebalzan-ci commit-msg "$1"
+fi
+
+# 2. A checkout of __CI_REPO__ next to this repo (or wherever CI_DIR points).
+ci_dir="${CI_DIR:-../__CI_REPO_NAME__}"
+if [ -f "$ci_dir/bin/cli.mjs" ]; then
+  exec node "$ci_dir/bin/cli.mjs" commit-msg "$1"
+fi
+
+echo "commit-msg: __CI_PACKAGE__ is not installed; commit message not checked locally."
+echo "Install it with: npm install --save-dev __CI_PACKAGE__"
+exit 0

package/templates/eslint.config.mjs

@@ -0,0 +1,6 @@
+// ESLint: the shared rules from @ebalzan/config, then this repo's own blocks
+// (generated by `ebalzan-ci onboard`). A later block wins for the files it
+// matches, e.g. { ignores: ['generated/'] } or { files: [...], rules: {...} }.
+import node from '@ebalzan/config/eslint/node'
+
+export default [...node]

package/templates/renovate.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>__CI_REPO__//renovate/tooling#__CI_REF__"]
+}