.github

Imported from leynier/alera (.github/AGENTS.md). Install upstream with npx skills add leynier/alera --skill .github. Copyright stays with the author.

AGENTS

Scope

This file applies to GitHub metadata and GitHub Actions workflows.

Workflow Policy

• Release jobs must be reproducible from a clean checkout.
• Build jobs must run on native runners for their platform.
• The shared job prologue lives in the composite action .github/actions/setup-flutter-workspace. Jobs must consume it rather than repeating the steps inline, so the sequence stays identical across pr.yml, desktop-build.yml, release-cut.yml, and warm-cache.yml. actions/checkout stays in the workflow, because a local composite action cannot be resolved before the repository is on disk.
• Any job that builds the desktop app or runs the Linux desktop integration tests must set up the pinned Rust toolchain (matching rust/rust-toolchain.toml) and the Rust build cache before the Flutter build, because the native build hooks compile the Rust alera terminal-host sidecar via cargo build --locked. Pass rust: 'true' to the composite action, which orders the steps correctly.
• Static analysis and root Flutter test jobs do not build the Linux desktop app and must pass linux-toolchain: 'false' to the composite action. Test jobs must still keep the native asset setup and preflight enabled.
• Flutter jobs that can run native asset hooks must set up Zig 0.16.0, restore the native asset cache, apply the temporary native asset CI workarounds, and run the native asset preflight before longer test/build commands. This keeps clean runners resilient when ghostty_vte, PDFium, or portable_pty prebuilt downloads are missing or transiently unavailable. This is the composite action's native-assets / preflight default.
• Workflows must check out with submodules: false and initialize only the submodules the job builds against, via .github/actions/init-required-submodules, before dependency resolution. The eight reference_projects/* submodules are contributor reading material excluded from analysis, and cloning them costs 649 MB per job. The initialization must stay --recursive, because third_party/dart_terminal nests the ghostty submodule and the native asset cache key hashes a file inside it: without --recursive, hashFiles() does not fail, it silently hashes a different set.
• The native asset cache key must stay keyed only on runner.os, runner.arch, and the hashed inputs. Namespacing it per job or per platform produces several copies of byte-identical content that compete for the repository cache budget.
• The Flutter version must stay pinned in the composite action rather than floating on channel: stable, so a Flutter release does not invalidate the SDK cache for every job on every platform at once, including the warm cache on main.
• Mobile Android CI copies .github/gradle/gradle_plugin_repos.init.gradle into ~/.gradle/init.d before flutter build apk. Flutter's included flutter_tools/gradle build has no pluginManagement block, so a cold runner only searches the plugin portal for that classpath; the portal 303s Kotlin artifacts to Maven Central and then fails to parse kotlin-gradle-plugins-bom. Do not patch $FLUTTER_ROOT for this: the Flutter SDK cache would pick up the mutation.
• Rust compiler outputs use sccache, installed by .github/actions/setup-rust-sccache. Trusted warm-cache, release, and pull-request rust jobs may connect it to a dedicated Cloudflare R2 bucket through the SCCACHE_R2_ACCOUNT_ID and SCCACHE_R2_BUCKET repository variables and the SCCACHE_R2_ACCESS_KEY_ID and SCCACHE_R2_SECRET_ACCESS_KEY repository secrets. Those credentials must have access only to the compiler-cache bucket and must never reuse the alera-updates bucket or its production credentials. Fork pull requests, incomplete configurations, and R2 authentication failures fall back to the runner-local cache so cache availability cannot block a build.
• Cargokit sets CARGOKIT_TEMP_DIR under the Flutter build directory, so the fully linked alera_native and code_forge outputs under build/**/cargokit_build keep a separate actions/cache entry. Only warm-cache.yml may save that entry, so pull requests and release jobs restore a shared copy instead of writing private copies into their own ref scopes. Windows CI must install the pinned LunarG Vulkan SDK (1.4.350.0) from the official installer and verify its SHA-256. Do not use winget: GitHub-hosted runners fail with APPINSTALLER_CLI_ERROR_SOURCE_DATA_MISSING (-1978335217). Windows Whisper/Vulkan jobs map scratch to R:\c with native cargo --target-dir at R:\c\n (not R:\c\alera_native or R:\alera-cargokit: those prefixes make vulkan-shaders-gen's nested TryCompile object exceed MAX_PATH and cl.exe reports C1083 with an empty generated-file name), set CMAKE_GENERATOR=Ninja so nested vulkan-shaders-gen cmake inherits Ninja, set _CL_=/Z7 /FS because cl.exe ignores CFLAGS, and set GGML_CCACHE=OFF so ggml does not wrap cl.exe with the rustc sccache (that pairing drops .obj files under Ninja).
• warm-cache.yml exists to populate the main Cargokit cache scope and the shared R2 compiler cache. It must keep using the same composite actions as the pull request and release jobs, so configuration cannot drift. It must keep running the real release build, since a prologue-only warm job would leave Cargokit cold, and it must keep the Linux warm-rust job, since that release build's rustc command line does not match PR clippy/test.
• Every workflow must declare an explicit permissions block. The repository default grants the whole GITHUB_TOKEN scope set to jobs that only read the checkout, so a compromised action or dependency inherits write access it never needed. Workflows that build, analyze, or test declare contents: read at the workflow level; a job that genuinely writes something adds the single scope it needs at the job level, as cloud-deploy.yml and release-cut.yml do. CodeQL's actions/missing-workflow-permissions rule reports a workflow that omits it.
• cache-cleanup.yml deletes the refs/pull/N/merge Actions caches when a pull request closes. It must keep actions: write as its only write permission and must not check out or execute pull request code.
• The Flutter test job is sharded by test file through tool/ci/select_test_shard.dart, never through flutter test --total-shards/--shard-index. That flag slices the tests inside each suite after the suite has been loaded, so every shard would still compile every test file and the split would buy nothing. Shards are packed by file size rather than round-robin so large widget suites cannot land on one runner. The TEST_SHARDS workflow env, the number of shard entries in the matrix, and the --expect-inputs argument of the coverage gate must stay in agreement, otherwise a lost shard silently shrinks the totals.
• pr.yml starts rust test immediately, then a changes job that runs .github/actions/select-ci-jobs (tool/ci/select_ci_jobs.dart) against the pull request file list. That composite must pass problem-matcher: false to dart-lang/setup-dart; the default matcher resolves dart-analyzer.json against the composite directory and 404s. Docs-only, landing-only, and cloud-only changes skip Flutter tests, generation, packages, mobile, and Rust cargo; unknown paths fail open and enable every job. workflow_dispatch always enables every job. rust test reuses that selector as its first step and skips cargo when Rust is not required, so the create→done critical path does not wait for changes or the Flutter fan-out. pr-ready is the required check: it treats skipped optional jobs as success, but changes, static, and rust test must succeed. Do not put paths: on the workflow itself, because a skipped pr-ready would block merge. Do not collect a second create→done sample by re-running a successful PR Checks run: GitHub keeps the original created_at, so attempt 2 inflates the wall. Dispatch a second run instead.
• The pull request rust checks use .github/actions/setup-rust-checks as two jobs in pr.yml (rust test and rust clippy). clippy-driver and rustc do not share rustc artifacts, so a sequential clippy-then-test job compiled the workspace twice and was the critical path of PR Checks; cargo test --workspace spends almost all of that step compiling. rust test has no needs: so it starts at workflow create; rust clippy still waits for changes so it does not take the first free runner from that compile. The composite owns the cargo flags, CMAKE_GENERATOR, RUSTFLAGS, and CARGO_PROFILE_DEV_DEBUG so warm-cache.yml's Linux warm-rust job can populate matching R2 keys. The Flutter release build in the warm matrix does not: release and clippy-driver command lines miss. Do not add a third rust leg; the extra runner setup would cost more than it buys back. Do not put needs: changes back on rust test: the post-filter queue was the create→done gap on #656 / #676. tool/ci/run_rust_workspace_tests.sh keeps --workspace on every cargo test so feature unification stays identical, then runs orchestration_review_regressions with --test-threads=1 because that binary drives real PTYs and flakes under cargo's default parallel test-target scheduling. Do not follow --no-run with --exclude or -p alera-cli: those package filters relink shared crates (~3 minutes each on PR Checks). Previous-host conformance downloads the pinned v0.49.0 published runtime tarball (SHA-256 pinned in tool/ci/host_compatibility.sh) instead of rebuilding that tag from source, which was ~5.5 minutes on the rust-test critical path. Assert the crate version and commit that tarball actually stamps (0.1.0 / 17a183f5), not the product tag.
• The desktop E2E job runs one flutter test invocation per file in integration_test/, never the directory. A directory run launches the app once and then fails to start it again for the next suite ("Unable to start the app on the device"), so the second and later files can never pass.
• The Linux startup performance measurement lives in startup-performance.yml on main, not in the pull request workflows. It launches the real app three times under xvfb, which made it the critical path of pr.yml while gating nothing, since it is invoked without --enforce-budget and its step is continue-on-error. Software rendering under xvfb on a shared runner also makes the raster metrics too noisy to read per pull request. If it is ever meant to gate, it needs --enforce-budget and a budget calibrated for xvfb first.
• Pull request workflows must not rerun solely because a draft pull request becomes ready for review; the existing checks for the same commit remain authoritative.
• Pull request workflows must declare a concurrency group keyed by ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} with cancel-in-progress: true, so a new commit cancels the superseded run instead of leaving it to saturate the shared runner pool. release-cut.yml is deliberately excluded: it keeps its own release-cut group with cancel-in-progress: false, because cancelling mid-publish would expose a partial release.
• Do not expose partial releases to users.
• cloud-deploy.yml is the only normal production path for cloud/, edge/, and infra/production/. Its third-party actions must stay pinned to immutable commit SHAs, its Google authentication must remain keyless through WIF, and only its cloud-production deployment job may read the Cloudflare tokens. Production plans containing deletes or replacements must fail before apply, and post-apply verification failures must attempt the documented Cloud Run and Worker rollback.
• release-cut.yml is the single manual release entry point. It must plan desktop and mobile independently, skip unchanged products, and preserve their separate version and tag sequences.
• Desktop release builds are split into native application builds, one cross-architecture runtime build per platform, and a deterministic runtime packaging job. The native application jobs reuse the unsigned sidecar and helper bundle already produced inside the app before platform signing. The packaging job must receive exactly one helper bundle per platform and both x64 and arm64 binaries, preserve executable modes through tarred intermediate artifacts, and finish before publish can run.
• Release automation must publish drafts first, verify required assets and update manifests, then publish public releases.
• Release notes must be product-scoped via tool/release/generate_release_notes.dart (desktop excludes mobile/ and landing/; mobile includes only mobile/), and only desktop stable releases may carry the Latest badge.
• Release workflows must not push release commits or tags until platform artifacts and update manifests have been generated and verified.
• Update indexes must be deployed only after the corresponding GitHub Release is public.
• Stable and release-candidate update indexes live under separate channel paths. Publishing one channel must not overwrite or delete the other channel.
• Stable release jobs must not enable automatic installation until the signed descriptor trust path is configured for the relevant platform.
• Release jobs must use schema v3 indexes, sign every platform release.json, and verify descriptor signatures plus artifact hashes before upload.
• Linux release jobs must publish signed APT and RPM repository metadata when Linux packages are included.
• The desktop package managers (publish_packages, publish_chocolatey) run only on stable cuts and only after the GitHub Release is public, because every manifest they push points at that release's assets. A failure there must not roll the release back: the release is already correct and the manifest can be pushed by hand. Release candidates never reach them, for the same reason they never reach the stable Linux repositories. Both jobs must skip with a warning when their secret is absent rather than fail, mirroring how the Apple and Windows signing steps treat theirs. Each destination repository is written with its own SSH deploy key (ALERA_HOMEBREW_TAP_DEPLOY_KEY, ALERA_SCOOP_BUCKET_DEPLOY_KEY) rather than one account-wide token, so a key that leaks or needs rotating reaches nothing else, and the step pins GitHub's host keys from api.github.com/meta instead of accepting them on first use: a runner that trusted a forged host key would push the manifest elsewhere and still report success.
• Signing secrets must be scoped only to release jobs that need them.

Issue And PR Policy

• Issue templates should collect platform details when behavior may differ across macOS, Windows, and Linux.
• Pull request templates should require validation notes, platform notes, and security/update risk notes when relevant.
• Workflow-created labels must be created idempotently when they may not exist in a fresh public repository.