@cratis/pi 7.100.0 → 7.102.0

package/package/corpus/skills/cratis-ci-pipeline-performance/references/required-checks-and-path-filters.md

@@ -0,0 +1,117 @@
+# Required checks, path filters and merge queue
+
+## Contents
+
+- The hang
+- Change detection and the aggregator
+- Keeping required checks stable
+- Merge queue
+
+Use this when skipping work by changed path, when a pull request hangs on a check
+that never reports, or when pull requests that pass alone break the default branch
+together.
+
+## The hang
+
+A required status check that never reports blocks the merge forever. A workflow
+that has a workflow-level `paths:` filter does not start when no path matches, so
+its required check stays pending. A job skipped through `if:` or `needs` reports
+`skipped`, which counts as passing. So: skip jobs, never whole required
+workflows.
+
+## Change detection and the aggregator
+
+Run a cheap `changes` job, gate heavy jobs on its outputs, and require one
+always-run aggregator.
+
+```yaml
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      code: ${{ steps.diff.outputs.code }}
+    steps:
+      - uses: actions/checkout@v7 # pin by full commit SHA
+        with:
+          fetch-depth: 2
+      - id: diff
+        run: |
+          if git diff --name-only HEAD^1 HEAD | grep -q -v -E '^(Documentation/|.*\.md$)'; then
+            echo "code=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "code=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  build:
+    needs: [changes]
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - run: echo build
+
+  checks:
+    if: always()
+    needs: [changes, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions: {}
+    steps:
+      - name: Require every needed job to pass or be skipped by design
+        env:
+          RESULTS: ${{ toJSON(needs.*.result) }}
+        run: |
+          echo "$RESULTS"
+          if echo "$RESULTS" | jq -e 'any(. == "failure" or . == "cancelled")' > /dev/null; then
+            exit 1
+          fi
+```
+
+- Require only `checks` in branch protection. Adding a job to the workflow then
+  means adding it to `needs`; nothing else changes.
+- `if: always()` is essential: without it the aggregator is skipped when a needed
+  job fails, and a skipped required check counts as passing.
+- List every job in `needs`. `needs.*.result` covers direct needs only, and a
+  job missing from the list can fail unnoticed.
+- The aggregator itself needs a runner, so it adds one scheduling boundary; keep
+  it on a cheap runner with a short timeout.
+- Keep workflow-level `paths:` for workflows nothing requires (a docs site
+  build). For one event, `paths` and `paths-ignore` cannot be combined; use
+  `paths` with `!` negation patterns.
+
+## Keeping required checks stable
+
+Branch protection matches check names. Renaming a job, changing a matrix key or
+moving a job to another workflow removes the old check and leaves the rule waiting
+on a name that no longer exists. When editing, list the check names before and
+after the change and keep them equal, or update the protection rule in the same
+step.
+
+Never make a required check conditional on the thing it validates: release,
+schema, migration and shared-library checks run on every pull request that can
+affect them. If the filter must be wide to be safe, keep it wide.
+
+## Merge queue
+
+Fits when pull requests pass individually and break after merge (semantic
+conflicts), and the cost of a broken default branch is higher than the extra
+validation. It does not shorten CI; it adds a validation of the queued result.
+
+```yaml
+on:
+  pull_request:
+  merge_group:
+    types: [checks_requested]
+```
+
+- The required workflows must run on `merge_group`, or the queue waits forever for
+  a check that never appears.
+- The aggregator must handle both events. For change detection on `merge_group`,
+  compare against `github.event.merge_group.base_sha` instead of `HEAD^1`.
+- Concurrency groups must keep merge-group runs apart from pull-request runs, and
+  must not cancel a merge-group run for a newer pull-request push.
+- Build concurrency, merge-group batching and the queue's own settings are
+  separate controls; change them one at a time.

package/package/corpus/skills/cratis-ci-pipeline-performance/references/runner-sizing-and-images.md

@@ -0,0 +1,65 @@
+# Runner sizing, images and cache layers
+
+Use this when every job is uniformly slow, when jobs spend time pulling or
+installing tools, or when deciding how to warm workspaces.
+
+## Contents
+
+- Cores per job before job count
+- Container images
+- Tools baked into the runner image
+- Cache layers and warm workspaces
+- Publish stages
+
+## Cores per job before job count
+
+Undersized runner pods (a small CPU request or limit) make every job slow, and more
+jobs then multiply the slowness. Before sharding:
+
+1. Print `nproc` and the memory limit at the start of a slow job, and read the
+   runner's resource configuration.
+2. If compile or test steps scale with cores, a larger runner or a higher CPU
+   request is the first lever. Runner capacity is an organization setting; request
+   it from the owner with the measured evidence, do not work around it in YAML.
+3. Re-measure with the same `ci-timings.sh` command.
+
+## Container images
+
+- Start only the services a job uses; pull only those images. Service containers
+  that a pull-request job never touches are pure wait.
+- Pull images in parallel (`docker pull a & docker pull b & wait`, checking each
+  exit status) rather than serially.
+- Do not pull a large release image to obtain one small tool; install or copy the
+  tool directly.
+- Avoid re-pulling a large handoff image in every downstream job; see publish
+  stages below.
+
+## Tools baked into the runner image
+
+Browsers, system packages and language toolchains installed on every run cost
+minutes every run. Bake them into the runner image and keep the install step only as
+a version check. Keep the image's contents versioned so a change is reviewable.
+
+## Cache layers and warm workspaces
+
+Prefer content-addressed caches, which are correct by construction, before
+warm volumes:
+
+1. A registry mirror or pull-through cache for images.
+2. A remote or registry-backed BuildKit cache (see `caching.md`).
+3. Package caches keyed by lock files.
+
+Warm workspaces (a prepared checkout and build output on a volume) are only safe
+when they come from a snapshot of a known-good state. Round-robin reuse of
+whichever runner last ran leaves stale or poisoned output. Publish and release
+builds stay cold: a clean build is part of what makes the artifact trustworthy.
+
+## Publish stages
+
+- Run independent stages in parallel, for example build alongside a dependency
+  audit, and join before publishing.
+- Build several images with `docker buildx bake` and a registry cache instead of
+  one serial build per image.
+- When one job builds an image that later jobs consume, keep the handoff small or
+  rebuild from cache, whichever the slowest-steps table shows is cheaper.
+- Keep the publish-path guardrails in `publish-pipelines.md`.

package/package/corpus/skills/cratis-ci-pipeline-performance/references/security-and-pinning.md

@@ -0,0 +1,73 @@
+# Security alongside speed
+
+Use this when a speed change adds or updates an action, edits `permissions:`,
+changes a trigger, or adds a cache. Speed changes widen the blast radius of a
+workflow more often than they narrow it. Run `zizmor` (security audits, including
+`unpinned-uses` and `excessive-permissions`) and `actionlint` (syntax, expressions,
+embedded shell; it does not check pinning) locally on every edited workflow when
+installed. Do not assume CI runs them.
+
+## Contents
+
+- Pin third-party actions
+- Minimal permissions
+- Untrusted code and triggers
+- Caches and artifacts
+- Verification
+
+## Pin third-party actions
+
+A tag can be moved to different code; a full commit SHA cannot. Pin every
+third-party action by its 40-character commit SHA and keep the version in a
+comment so updates remain reviewable:
+
+```yaml
+- uses: actions/checkout@<40-character-sha> # v7
+```
+
+- Resolve a tag to its commit with `gh api repos/OWNER/REPO/commits/TAG --jq .sha`
+  and confirm it matches the release you intend.
+- Examples in this skill show a major tag with a "pin by full commit SHA" note;
+  the major shown is not a recommendation to pin a tag.
+- Actions of the `Cratis` organization follow the owning repository's convention.
+- Let a dependency-update tool bump pinned SHAs so pinning does not freeze them.
+
+## Minimal permissions
+
+- Set `permissions:` at the job level, not the workflow level, and grant only
+  what the job uses. Start from `contents: read`, or `permissions: {}` for a job
+  that touches no repository content.
+- Grant write scopes (`contents`, `packages`, `pull-requests`, `id-token`) only to
+  the job that needs them, such as the publisher.
+- Do not use a personal access token where the workflow token suffices.
+
+## Untrusted code and triggers
+
+- Never check out or run code from a pull request under `pull_request_target`
+  or `workflow_run` with the base repository's credentials: it exposes secrets
+  and a write token to fork code.
+- `pull_request` from a fork has no secrets, which is the safe default for
+  verification.
+- Never route `pull_request` jobs of a public repository to self-hosted runners.
+- Pass untrusted values (branch names, titles, comment bodies) to scripts through
+  `env:`, never interpolated into `run:` with `${{ }}`.
+
+## Caches and artifacts
+
+- Caches must not contain secrets. A cache saved from the default branch is
+  readable by every branch; a cache saved by a pull request is scoped to it.
+- Do not restore a pull-request cache in a privileged workflow.
+- Use `persist-credentials: false` on `actions/checkout` when the job does not
+  push, so the token is not left in the checkout.
+- Artifacts are not private from other jobs in the run; do not put credentials
+  in them.
+
+## Verification
+
+```bash
+actionlint .github/workflows/*.yml
+zizmor .github/workflows/
+```
+
+Pass means exit `0` and no findings. Report a tool that is not installed as not
+run. Resolve findings in the workflow; suppress one only with a recorded reason.

package/package/corpus/skills/cratis-ci-pipeline-performance/references/sources.md

@@ -0,0 +1,33 @@
+# Sources and attribution
+
+The structure and method of this skill adapt two MIT-licensed skills. The text
+here is new; no passage is copied.
+
+- `github-actions-efficiency` from github/awesome-copilot, MIT license:
+  https://github.com/github/awesome-copilot/blob/main/skills/github-actions-efficiency/SKILL.md.
+  Adapted: measure before changing, guardrails against hiding required
+  validation, separating repository changes from organization settings, a
+  static-only analysis label, expected against measured savings, and wall clock
+  reported apart from runner-minutes.
+- `ci-speedup` from starslingdev/skills, MIT license:
+  https://github.com/starslingdev/skills/blob/main/skills/ci-speedup/SKILL.md.
+  Adapted: the critical path over required checks, queue delay as a separate
+  signal, shard imbalance, and an always-run aggregator that checks every
+  `needs.*.result`, including for `merge_group`.
+
+Primary documentation consulted for factual claims:
+
+- GitHub Docs, dependency caching, secure use of Actions, concurrency control and
+  merge queue.
+- Docker Docs, GitHub Actions cache backend (custom `scope`).
+- Microsoft Learn, `dotnet test` blame options and Microsoft.Testing.Platform
+  retry and crash/hang extensions.
+- The `actionlint` and `zizmor` project documentation.
+
+- Studio CI investigation (Einar Ingebrigtsen, Cratis, 2026): the method of counting
+  compiles per push, sizing cores before job count, finding test time hidden outside
+  per-test timing, testing each guarantee where it can break, and layering
+  content-addressed caches before warm workspaces. Reduced here to generic levers.
+
+The Cratis-specific levers come from the shared `Cratis/Workflows` cache actions
+and the build-once, artifact and shard layout used in the Arc repository.

package/package/corpus/skills/cratis-ci-pipeline-performance/references/test-setup-cost.md

@@ -0,0 +1,82 @@
+# Test setup cost and where to test a guarantee
+
+Use this when a test lane is slow but the runner's per-test times look small, when
+a suite re-tests a dependency, or when compile errors surface late.
+
+## Contents
+
+- Time hidden outside per-test timing
+- Profile the test host
+- Fix setup upstream
+- Test each guarantee where it can break
+- Surface compile errors early
+- Count compiles per push
+
+## Time hidden outside per-test timing
+
+Compare the test runner's reported total test time with the wall time of the test
+step. A large gap means time is spent outside what the runner attributes to tests:
+per-class or per-fixture setup (scenario, host or container construction), discovery,
+or process start. Specification frameworks that build a context in a base-class
+setup often charge it to no test at all.
+
+1. Read both numbers from the same run: the runner's summary and the step duration
+   from `ci-timings.sh`'s slowest-steps table.
+2. If setup dominates, sharding only divides the waste across more jobs. Fix the
+   setup first.
+
+## Profile the test host
+
+Measure before guessing, with the language's profiler on the test process:
+
+```bash
+dotnet tool install --global dotnet-trace
+dotnet-trace collect --format speedscope -- dotnet test Project.Specs --no-build --configuration Release
+```
+
+Read the inclusive time of the setup methods. Pass means the profile names the
+dominant constructor or discovery call; a flat profile means the cost is elsewhere
+(I/O, container start, process start).
+
+## Fix setup upstream
+
+Per-test construction of identical, immutable data is the usual cause. Fix it where
+the data originates rather than skipping specifications:
+
+- Build shared metadata (type discovery, schemas, registrations) once per process
+  and reuse it across scenarios.
+- Share expensive generators and caches instead of creating one per instance.
+- Cache reflection results that are recomputed on every call.
+- Use a prebuilt service collection as a template and copy it per test.
+- Do not share mutable state between tests to save time; share only what is immutable.
+
+A fix belongs in the library that owns the setup, not in each consuming repository.
+
+## Test each guarantee where it can break
+
+- A suite that tests a dependency's semantics belongs in that dependency's own
+  repository. In a consumer, run it only when the dependency pin changes, or nightly.
+- Check a wire or API shape with a committed snapshot and a diff, not a live
+  integration run.
+- Mixed-version or upgrade matrices run nightly or before a release, not on every
+  pull request.
+- Where a behavior is only meaningful in a deployed environment, prefer a
+  post-deploy synthetic check plus unit specifications and contract snapshots over
+  a pull-request integration environment.
+- Never remove the only check of a required guarantee; relocate it and say where it
+  now runs.
+
+## Surface compile errors early
+
+A pull request that fails to compile should fail in the first minutes, not after a
+long test leg. Make a fast build or lint job a `needs` of the long legs, and keep
+it short enough that it is not itself the critical path.
+
+## Count compiles per push
+
+Count how many times one push compiles the same code across all jobs and
+workflows (`dotnet build` or `dotnet test` without `--no-build` in the step list).
+Each extra compile is avoidable: build once, reuse the output (see
+`build-once-and-shard.md`). Analyzers can roughly double compile time; run them once
+in a parallel lint job and disable them in the shared build, while keeping the
+strictest configuration that consumers enforce somewhere on the required path.