/pipe

Advanced Patterns

Purpose: Cover monorepo CI, self-hosted runners, multi-platform builds, advanced deployment flows, service containers, and deep workflow debugging.

Contents

• Monorepo CI
• Self-hosted runners
• Multi-platform builds
• Deployment patterns
• Service containers
• Debugging
• Expressions and functions

Monorepo CI

Workflow-level paths filters are not enough for job-level routing in a monorepo.

Safe default:

• detect changed areas first
• run only affected jobs
• keep one always-reporting gate for required checks

Self-Hosted Runners

Use self-hosted runners only when GitHub-hosted runners cannot satisfy networking, hardware, or compliance constraints.

Rules:

• prefer ephemeral runners
• prefer ARC for elastic scale
• use explicit labels and runner groups
• never use self-hosted runners for public repositories
• rebuild runner images regularly

Multi-Platform Builds

• Use docker/setup-qemu-action and docker/setup-buildx-action for multi-arch image builds.
• Keep full OS matrices for PRs, release, or nightly flows, not every push.
• Prefer Ubuntu by default and add Windows/macOS only when required by the product surface.

Deployment Patterns

Deployment rules:

• protect environments with reviewers
• do not cancel active production deploys automatically
• keep rollback entry points explicit

Service Containers

Use service containers for fast integration tests when the dependency can be expressed locally.

Checklist:

• pin service images
• add health checks
• isolate credentials
• use them only in jobs that need them

Debugging

Typical failure classes:

• trigger did not match filters
• required check name mismatch
• hidden dependency on repo secrets or environment
• unsupported act behavior for cloud-only or service-heavy jobs

Expressions And Functions

Useful functions to keep close:

• success()
• failure()
• cancelled()
• always()
• contains()
• startsWith()
• hashFiles()
• fromJSON()
• toJSON()

Critical Decision Rules Long Form (SKILL.md excerpt)

Per-Recipe Behavior Notes (SKILL.md excerpt)

• workflow: New workflow skeleton. Declare trigger set, permissions: {} baseline, runner choice, and cache strategy at Orchestrate. SHA-pin every third-party action. Validate with actionlint before handoff.
• reusable: Extract reusable workflow (multi-job) or composite action (multi-step) only after 3+ copies. Version interface via @vX tag plus commit SHA. Document inputs / outputs / secrets: contract; prefer explicit secrets: over secrets: inherit.
• security: Harden an existing workflow. Minimize permissions, pin SHAs, switch long-lived cloud credentials to OIDC, scope env protection rules, add artifact attestations. Never checkout fork code in pull_request_target.
• pr-automation: Label, assign, required checks, merge queue, branch protection. Use pull_request_target only for metadata; gate privileged actions behind label or maintainer approval.
• matrix: Design a matrix build. Enumerate axes (OS x runtime x arch), use include to add sparse combinations and exclude to drop impossible ones. Set fail-fast: false when axes give independent signal. Cap max-parallel to bound concurrency. Prefer dynamic matrices via fromJSON when axes are computed (changed packages, supported versions). Keep fan-out under ~100 jobs; expand full combinations only on nightly or release branches. Pair with cache for per-axis key strategy. For provider-agnostic CI topology, route to Gear ci.
• cache: Design actions/cache layout. Key by runner.os + lockfile hash (hashFiles('**/pnpm-lock.yaml')); add restore-keys for graceful fallback. Cross-OS compatibility: include runner.arch for native binaries. Monorepo: separate caches per package manager root to avoid cross-contamination. Track cache-hit telemetry via step output or Data Stream. Stay under the 10 GB repo budget (entries evict after 7 days of no access); prefer built-in setup-* caches first. For provider-agnostic CI caching posture, route to Gear ci.
• secret: Design the GHA secret surface. Prefer OIDC federation to AWS (aws-actions/configure-aws-credentials) / GCP (google-github-actions/auth) / Azure (azure/login) over long-lived cloud credentials — scope via sub claim (repo:org/name:environment:prod). Separate environment secrets (deploy-time, gated) from repo secrets (shared). Use vars for non-sensitive config and secrets for sensitive values; both are masked only when declared as secrets. Add ::add-mask:: for runtime-derived sensitive values. Fork-PR safety: pull_request from forks does NOT inherit secrets (by design) — never add pull_request_target to access them. For application-layer secret management (Vault, AWS Secrets Manager, Doppler, sealed-secrets), route to Gear secret. For secret leakage scans in source code, route to Sentinel — this recipe designs the CI architecture so secrets never enter code in the first place.