|
| 1 | +--- |
| 2 | +name: local-ci |
| 3 | +description: Run this repository's local CI parity commands and `pnpm run ci:local` jobs. Use when validating a change against the same job shapes used in GitHub Actions, choosing the smallest local CI job for a package, workflow, E2E, Metro, devtools, bundle-size, or build-and-test change. |
| 4 | +--- |
| 5 | + |
| 6 | +# Local CI |
| 7 | + |
| 8 | +Use the local CI runner and Turbo/package scripts as the source of truth for validation in this repo. |
| 9 | + |
| 10 | +## Quick Start |
| 11 | + |
| 12 | +1. Start with the smallest deterministic check that matches the change. |
| 13 | +2. Prefer `pnpm run ci:local --only=<job>` for CI-parity validation. |
| 14 | +3. Prefer direct Turbo or package scripts only when they are the smaller equivalent of the CI job. |
| 15 | +4. Report exactly which command ran, what failed first, and which expected checks were skipped. |
| 16 | + |
| 17 | +## Workflow |
| 18 | + |
| 19 | +### 1. Inspect available local CI jobs |
| 20 | + |
| 21 | +Run: |
| 22 | + |
| 23 | +```bash |
| 24 | +pnpm run ci:local --list |
| 25 | +``` |
| 26 | + |
| 27 | +Use this when the right job is unclear or when the repo may have added or renamed jobs. |
| 28 | + |
| 29 | +For the current job map, read [references/jobs.md](./references/jobs.md). |
| 30 | + |
| 31 | +### 2. Pick the smallest matching job |
| 32 | + |
| 33 | +Use these defaults: |
| 34 | + |
| 35 | +- Package code in `packages/*`: start with `build-and-test` only if the change is broad; otherwise prefer package build/test commands. |
| 36 | +- Metro packages or Metro workflow changes: use `build-metro`, then Metro E2E jobs only if relevant. |
| 37 | +- E2E app changes: run the matching `e2e-*` job instead of `build-and-test`. |
| 38 | +- Devtools workflow or Playwright/devtools changes: run `devtools`. |
| 39 | +- Bundle-size workflow/reporting changes: run `bundle-size`. |
| 40 | +- GitHub workflow syntax only: use `actionlint` locally only to see skip behavior; the actual action is CI-only. |
| 41 | +- Broad CI, packaging, publint, Turbo, or shared runtime changes: run `build-and-test`. |
| 42 | + |
| 43 | +### 3. Run commands in CI order |
| 44 | + |
| 45 | +When reproducing CI, use the same command shape as the repo: |
| 46 | + |
| 47 | +```bash |
| 48 | +pnpm run ci:local --only=build-and-test |
| 49 | +pnpm run ci:local --only=devtools |
| 50 | +pnpm run ci:local --only=e2e-runtime |
| 51 | +``` |
| 52 | + |
| 53 | +To run more than one job: |
| 54 | + |
| 55 | +```bash |
| 56 | +pnpm run ci:local --only=build-and-test,bundle-size |
| 57 | +``` |
| 58 | + |
| 59 | +### 4. Interpret failures correctly |
| 60 | + |
| 61 | +- Treat the first failing step as the actionable failure. |
| 62 | +- Ignore known noisy warnings unless they exit non-zero. |
| 63 | +- Distinguish repo-wide drift from changed-file gates. |
| 64 | +- If `ci:local` fails in `Check code format`, inspect the changed-file formatter result before running broader builds. |
| 65 | +- If a dependency build outside the touched scope fails, note it separately as an unrelated blocker. |
| 66 | + |
| 67 | +## Common Cases |
| 68 | + |
| 69 | +### Broad package or runtime/plugin change |
| 70 | + |
| 71 | +Run: |
| 72 | + |
| 73 | +```bash |
| 74 | +pnpm run ci:local --only=build-and-test |
| 75 | +``` |
| 76 | + |
| 77 | +If that fails on format first, fix the changed files before rerunning the whole job. |
| 78 | + |
| 79 | +### One package only |
| 80 | + |
| 81 | +Prefer the smaller direct command first: |
| 82 | + |
| 83 | +```bash |
| 84 | +pnpm exec turbo run build --filter=@module-federation/<pkg> |
| 85 | +pnpm exec turbo run test --filter=@module-federation/<pkg> --force |
| 86 | +``` |
| 87 | + |
| 88 | +Then run `build-and-test` only if the user asks for CI parity or the package change affects shared build/runtime behavior. |
| 89 | + |
| 90 | +### E2E change |
| 91 | + |
| 92 | +Run the matching job from [references/jobs.md](./references/jobs.md), not the whole matrix. |
| 93 | + |
| 94 | +### Workflow change |
| 95 | + |
| 96 | +Use the local CI job if one exists for the workflow's behavior. For workflow syntax, pair local validation with the repo's actionlint path when relevant. |
| 97 | + |
| 98 | +## Notes |
| 99 | + |
| 100 | +- `ci:local` sets `CI=true` and mirrors the repo workflow order. |
| 101 | +- Some jobs intentionally skip GitHub-only actions such as `actionlint` and `bundle-size-comment`. |
| 102 | +- The repo uses `pnpm`, Node 20, and Turbo as the standard execution path. |
| 103 | +- In worktrees, still use Turbo/package scripts directly as documented by the repo instructions. |
0 commit comments