diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000..5957712 --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,213 @@ +# ───────────────────────────────────────────────────────────────────────────── +# SOURCE OF TRUTH: petry-projects/.github/standards/workflows/copilot-setup-steps.yml +# Standard: petry-projects/.github/standards/ci-standards.md#11-copilot-cloud-agent-setup +# +# ADOPTING THIS WORKFLOW: +# 1. Copy this file to .github/workflows/copilot-setup-steps.yml in your repo. +# 2. Keep every REQUIRED section — do NOT remove the checkout or verify steps. +# 3. Uncomment and adapt the stack blocks that match your repo's tech stack. +# 4. Delete (not just comment out) stacks that do not apply after initial setup. +# 5. Merge to the default branch — the workflow only triggers from the default branch. +# 6. Run manually from Actions → "Copilot Setup Steps" → "Run workflow" to verify. +# +# WHAT THIS FILE DOES: +# Bootstraps Copilot cloud agent's ephemeral environment BEFORE the agent starts +# working on your repo. Pre-installing dependencies deterministically: +# • Speeds up every agent session (no trial-and-error dependency discovery) +# • Makes private/internal packages available (impossible for the agent alone) +# • Ensures exact tool versions that match your CI pipeline +# Without this file the agent installs dependencies itself — slower, non-deterministic, +# and unreliable for repos with private packages or complex build graphs. +# +# SEE ALSO: +# AGENTS.md — authoritative development standards for this repo +# .github/copilot-instructions.md — always-on Copilot instructions (summary of AGENTS.md) +# .github/instructions/ — path-scoped instruction files per language +# +# CONSTRAINTS (enforced by GitHub, documented at docs.github.com): +# • Job MUST be named `copilot-setup-steps` to be recognized by Copilot cloud agent +# • timeout-minutes maximum: 59 (hard limit) +# • Customizable fields: steps, permissions, runs-on, services, snapshot, timeout-minutes +# • All other job-level settings are silently ignored by GitHub +# • fetch-depth on checkout is always overridden by the agent — do not rely on it here +# • This file MUST be present on the default branch to take effect +# +# AGENTS — READ BEFORE EDITING: +# This file is a PER-REPO TEMPLATE (Tier 2). There is no central reusable workflow +# because setup steps are inherently tech-stack-specific. Each repo owns its copy. +# Stay within the patterns documented in ci-standards.md §11. Do not change: +# • the job name (`copilot-setup-steps`) +# • the fork guard condition +# • the trigger events +# • the verify-environment step +# For changes to the org-wide pattern, open a PR against this file in +# petry-projects/.github and propagate to the fleet. +# ───────────────────────────────────────────────────────────────────────────── + +name: "Copilot Setup Steps" + +# Run automatically when this file changes (validates the setup steps work), +# and allow manual runs from the Actions tab at any time. +# NOT a standard CI trigger — this file should NOT be added to push: branches: [main]. +on: + workflow_dispatch: + push: + paths: + - .github/workflows/copilot-setup-steps.yml + pull_request: + paths: + - .github/workflows/copilot-setup-steps.yml + +# Defense-in-depth: reset top-level permissions; set exact grants per-job. +# Pattern from envoyproxy/envoy and the org Permissions Policy (ci-standards.md). +permissions: {} + +jobs: + # ── REQUIRED: Job name must be exactly `copilot-setup-steps` ──────────────── + copilot-setup-steps: + # Skip on fork-origin pull requests — forks cannot access org secrets required for private packages. + # `github.event.repository.fork` reflects the base repo (always false for org repos); the + # correct guard is on the PR head repo so that external fork PRs are skipped while direct + # pushes and manual runs always proceed. + if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false + + runs-on: ubuntu-latest + + # Adjust upward only if your build or download steps genuinely need more time. + # Hard maximum enforced by GitHub is 59 minutes. + timeout-minutes: 30 + + # Minimum permissions — Copilot receives its own separate token for its operations. + # Add `packages: read` if pulling from GitHub Packages (GHCR or npm private registry). + permissions: + contents: read + + steps: + # ── REQUIRED ────────────────────────────────────────────────────────────── + # Checkout the repository so dependency manifests (package.json, go.mod, etc.) + # are available for the install steps below. + # Note: fetch-depth is always overridden by the agent — set it here only if + # your install steps need history (rare). + - name: Checkout code + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + + # ── NODE.JS / NPM ────────────────────────────────────────────────────────── + # Uncomment for repos using npm (TypeScript, React, Electron, Google Apps Script). + # Use node-version-file: .nvmrc if the repo maintains a .nvmrc; otherwise pin + # the version to match the CI pipeline and the org standard (Node.js 22 LTS). + # + # - name: Set up Node.js + # uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + # with: + # node-version: "22" # or: node-version-file: .nvmrc + # cache: "npm" + # + # - name: Install Node.js dependencies + # run: npm ci --ignore-scripts + + # ── NODE.JS / PNPM ──────────────────────────────────────────────────────── + # Uncomment for repos using pnpm (e.g., broodly TypeScript layer). + # pnpm must be set up before setup-node when using pnpm cache. + # + # - name: Set up pnpm + # uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4 + # + # - name: Set up Node.js (pnpm) + # uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + # with: + # node-version: "22" + # cache: "pnpm" + # + # - name: Install Node.js dependencies (pnpm) + # run: pnpm install --frozen-lockfile --ignore-scripts + + # ── GO ──────────────────────────────────────────────────────────────────── + # Uncomment for repos with Go code (e.g., broodly API layer). + # Pin go-version to match go.mod to avoid silent toolchain upgrades. + # For monorepos, set cache-dependency-path to the correct go.sum path. + # + # - name: Set up Go + # uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5 + # with: + # go-version: "stable" # or: go-version-file: go.mod + # cache-dependency-path: go.sum + # + # - name: Download Go dependencies + # run: go mod download + + # ── PYTHON ──────────────────────────────────────────────────────────────── + # Uncomment for repos with Python code. + # Pin python-version to a specific minor version for reproducibility. + # + # - name: Set up Python + # uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + # with: + # python-version: "3.12" # pin to match your runtime + # cache: "pip" + # + # - name: Install Python dependencies + # run: pip install -r requirements.txt + + # ── OPTIONAL: Additional build artifacts ────────────────────────────────── + # If the agent needs pre-built artifacts to run tests (e.g., a Next.js build, + # a compiled binary, or generated types), add a build step here. + # Keep it minimal — the agent will run its own build steps when needed. + # + # - name: Build + # run: npm run build + + # ── OPTIONAL: gh-aw MCP extension ──────────────────────────────────────── + # Installs GitHub Advanced Workflows (gh-aw), a GitHub-developed MCP server + # that gives Copilot cloud agent extended GitHub API access (web search, + # enhanced PR tools, and more). Used by github/copilot-sdk, TryGhost/Ghost, + # and github/awesome-copilot. Recommended for any repo doing heavy GitHub + # platform work (issue triage, PR automation, release management). + # Pin the version to a specific SHA for supply-chain safety. + # + # - name: Install gh-aw MCP extension + # uses: github/gh-aw/actions/setup-cli@ce1794953e0ec42adc41b6fca05e02ab49ee21c3 + # with: + # version: v0.49.3 + + # ── REQUIRED ────────────────────────────────────────────────────────────── + # Environment verification — always runs last. Fails loud if something is + # missing so the problem is caught here rather than mid-agent-session. + # Also surfaces the agent instruction files so session logs confirm they + # were found before the agent began working. + - name: Verify environment + run: | + echo "=== petry-projects Copilot cloud agent environment ===" + echo "Repository : ${{ github.repository }}" + echo "Ref : ${{ github.ref }}" + echo "Runner : ${{ runner.os }} / ${{ runner.arch }}" + echo "" + echo "--- Installed tool versions ---" + git --version + gh --version 2>/dev/null | head -1 || echo "gh: not installed" + node --version 2>/dev/null || echo "node: not installed" + npm --version 2>/dev/null || echo "npm: not installed" + go version 2>/dev/null || echo "go: not installed" + python --version 2>/dev/null || echo "python: not installed" + echo "" + echo "--- Agent instruction files ---" + if [ -f "AGENTS.md" ]; then + echo "✅ AGENTS.md ($(wc -l < AGENTS.md) lines)" + else + echo "❌ AGENTS.md — MISSING. Add this file per agent-standards.md." + exit 1 + fi + if [ -f ".github/copilot-instructions.md" ]; then + echo "✅ .github/copilot-instructions.md" + else + echo "ℹ️ .github/copilot-instructions.md — not present (optional but recommended)" + fi + # Count path-scoped instruction files (guard against missing directory) + INSTR_COUNT=0 + if [ -d ".github/instructions" ]; then + INSTR_COUNT=$(find .github/instructions -name "*.instructions.md" | wc -l) + fi + echo "ℹ️ .github/instructions/: ${INSTR_COUNT} file(s)" + echo "" + echo "✅ Setup complete — Copilot cloud agent is ready to work" diff --git a/.gitignore b/.gitignore index 3846379..1212005 100644 --- a/.gitignore +++ b/.gitignore @@ -385,8 +385,8 @@ private.yml # be committed accidentally. .claude/worktrees/ .worktrees/ +.dev-lead/ # ============================================================================ # End of petry-projects secrets baseline # ============================================================================ -.dev-lead/ diff --git a/actionlint b/actionlint new file mode 100755 index 0000000..a6da031 Binary files /dev/null and b/actionlint differ diff --git a/standards/workflows/copilot-setup-steps.yml b/standards/workflows/copilot-setup-steps.yml index c7fe318..5957712 100644 --- a/standards/workflows/copilot-setup-steps.yml +++ b/standards/workflows/copilot-setup-steps.yml @@ -90,6 +90,8 @@ jobs: # your install steps need history (rare). - name: Checkout code uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false # ── NODE.JS / NPM ────────────────────────────────────────────────────────── # Uncomment for repos using npm (TypeScript, React, Electron, Google Apps Script).