Epic 7.3: Launch Checklist — v2.0.0 Release #71
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # ============================================================================ | |
| # Phase Gate Enforcement — Fail-Closed PR Merge Guard | |
| # ============================================================================ | |
| # | |
| # PURPOSE: Block merges for PRs that reference issues in phases whose | |
| # prerequisites are not yet complete. If this Action crashes or | |
| # fails to report a status, the merge is BLOCKED (fail-closed). | |
| # | |
| # PATTERN LINEAGE: | |
| # - eight-eyes/circuit_breaker.py → retry + fail-closed design | |
| # - squad-audit/squad-label-enforce.yml → structured PR comments | |
| # - squad-audit/squad-promote.yml → prerequisite validation gates | |
| # | |
| # REQUIRED: Branch protection must require this check ("Phase Gate Enforcement") | |
| # ============================================================================ | |
| name: Phase Gate Enforcement | |
| on: | |
| pull_request: | |
| types: [opened, synchronize, reopened, labeled, unlabeled, edited] | |
| branches: [main] | |
| permissions: | |
| contents: read | |
| issues: read | |
| pull-requests: write | |
| # Concurrency: cancel in-flight runs for the same PR | |
| concurrency: | |
| group: phase-enforce-${{ github.event.pull_request.number }} | |
| cancel-in-progress: true | |
| jobs: | |
| enforce: | |
| name: "Phase Gate Enforcement" | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout BASE branch (not PR — prevents self-modification attack) | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: ${{ github.event.pull_request.base.sha }} | |
| - name: Install js-yaml | |
| run: npm install js-yaml@4 --no-save --silent 2>/dev/null | |
| - name: Load phase configuration | |
| id: config | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const fs = require('fs'); | |
| const yaml = require('js-yaml'); | |
| const configPath = '.github/phase-config.yml'; | |
| if (!fs.existsSync(configPath)) { | |
| core.setFailed('FAIL-CLOSED: .github/phase-config.yml not found. Cannot enforce phase gates.'); | |
| return; | |
| } | |
| try { | |
| const raw = fs.readFileSync(configPath, 'utf8'); | |
| const config = yaml.load(raw); | |
| // Validate structure | |
| if (!config.phases || typeof config.phases !== 'object') { | |
| core.setFailed('FAIL-CLOSED: phase-config.yml missing "phases" key.'); | |
| return; | |
| } | |
| // Check for circular dependencies | |
| const visited = new Set(); | |
| const visiting = new Set(); | |
| function detectCycle(phase) { | |
| if (visiting.has(phase)) return true; | |
| if (visited.has(phase)) return false; | |
| visiting.add(phase); | |
| const prereqs = config.phases[phase]?.prerequisites || []; | |
| for (const p of prereqs) { | |
| if (!config.phases[p]) { | |
| core.setFailed(`FAIL-CLOSED: Phase "${phase}" has unknown prerequisite "${p}"`); | |
| return true; | |
| } | |
| if (detectCycle(p)) return true; | |
| } | |
| visiting.delete(phase); | |
| visited.add(phase); | |
| return false; | |
| } | |
| for (const phase of Object.keys(config.phases)) { | |
| if (detectCycle(phase)) { | |
| core.setFailed(`FAIL-CLOSED: Circular dependency detected involving "${phase}"`); | |
| return; | |
| } | |
| } | |
| core.setOutput('config', JSON.stringify(config)); | |
| core.info('✅ Phase configuration loaded and validated'); | |
| } catch (err) { | |
| core.setFailed(`FAIL-CLOSED: Failed to parse phase-config.yml: ${err.message}`); | |
| } | |
| - name: Enforce phase gates | |
| if: steps.config.outputs.config | |
| uses: actions/github-script@v7 | |
| env: | |
| PHASE_CONFIG: ${{ steps.config.outputs.config }} | |
| with: | |
| script: | | |
| // ================================================================= | |
| // ENFORCEMENT ENGINE — Fail-closed by design | |
| // ================================================================= | |
| // | |
| // If ANY step throws an unhandled exception, the Action fails, | |
| // no status is reported, and the merge is blocked. | |
| // This is intentional. We retry API calls, but logic errors = deny. | |
| // ================================================================= | |
| const MAX_RETRIES = 3; | |
| const RETRY_DELAYS = [1000, 3000, 5000]; // ms | |
| // Retry wrapper (from eight-eyes circuit breaker pattern) | |
| async function withRetry(fn, label) { | |
| let lastErr; | |
| for (let i = 0; i <= MAX_RETRIES; i++) { | |
| try { | |
| return await fn(); | |
| } catch (err) { | |
| lastErr = err; | |
| if (i < MAX_RETRIES) { | |
| const delay = RETRY_DELAYS[i] || 5000; | |
| core.warning(`[retry ${i + 1}/${MAX_RETRIES}] ${label}: ${err.message} — retrying in ${delay}ms`); | |
| await new Promise(r => setTimeout(r, delay)); | |
| } | |
| } | |
| } | |
| throw new Error(`${label} failed after ${MAX_RETRIES} retries: ${lastErr.message}`); | |
| } | |
| // ---- Load config (via env to avoid string interpolation attacks) ---- | |
| const config = JSON.parse(process.env.PHASE_CONFIG); | |
| const phaseConfig = config.phases; | |
| const escapeHatch = config.escape_hatch || {}; | |
| const pr = context.payload.pull_request; | |
| const prBody = (pr.body || '') + ' ' + (pr.title || ''); | |
| // Audit log accumulator | |
| const audit = { | |
| pr_number: pr.number, | |
| pr_title: pr.title, | |
| timestamp: new Date().toISOString(), | |
| run_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`, | |
| checks: [], | |
| verdict: null, | |
| }; | |
| function addCheck(name, passed, detail) { | |
| const icon = passed ? '✅' : '❌'; | |
| audit.checks.push({ name, passed, detail, icon }); | |
| core.info(`${icon} ${name}: ${detail}`); | |
| } | |
| // ---- LAYER 4: Escape hatch (check first — may short-circuit) ---- | |
| const prLabels = pr.labels.map(l => l.name); | |
| const bypassLabel = escapeHatch.label || 'emergency:bypass'; | |
| const hasBypassLabel = prLabels.includes(bypassLabel); | |
| if (hasBypassLabel) { | |
| // KEY 1: Actor must be in allowlist | |
| const allowedActors = escapeHatch.allowed_actors || []; | |
| const actor = context.actor; | |
| if (allowedActors.length > 0 && !allowedActors.includes(actor)) { | |
| addCheck('Emergency bypass', false, `Actor @${actor} is not authorized to invoke bypass. Allowed: ${allowedActors.join(', ')}`); | |
| // Fall through to normal enforcement (deny) | |
| } else { | |
| // KEY 2: Reason pattern must be present (not inside HTML comments) | |
| const reasonPattern = escapeHatch.reason_pattern || '## ⚠️ Bypass Reason'; | |
| const minLength = escapeHatch.min_reason_length || 30; | |
| // Strip HTML comments before searching to prevent template placeholder match | |
| const bodyNoComments = (pr.body || '').replace(/<!--[\s\S]*?-->/g, ''); | |
| const reasonIdx = bodyNoComments.indexOf(reasonPattern); | |
| if (reasonIdx === -1) { | |
| addCheck('Emergency bypass', false, `Label \`${bypassLabel}\` present but no "${reasonPattern}" section in PR body (outside HTML comments). Both keys required.`); | |
| // Don't short-circuit — fall through to fail | |
| } else { | |
| const reasonText = bodyNoComments.slice(reasonIdx + reasonPattern.length).trim().split('\n')[0]; | |
| if (!reasonText || reasonText.length < minLength) { | |
| addCheck('Emergency bypass', false, `Bypass reason too short (${(reasonText || '').length}/${minLength} chars). Explain WHY this bypass is necessary.`); | |
| } else { | |
| addCheck('Emergency bypass', true, `OVERRIDE by @${actor}: "${reasonText.slice(0, 100)}"`); | |
| // Short-circuit: bypass granted | |
| audit.verdict = 'BYPASS'; | |
| audit.bypass_reason = reasonText; | |
| audit.bypass_actor = actor; | |
| const auditComment = formatAuditComment(audit); | |
| await postAuditComment(auditComment); | |
| core.warning(`⚠️ EMERGENCY BYPASS by @${actor}: ${reasonText.slice(0, 100)}`); | |
| return; // Exit with success | |
| } | |
| } | |
| } | |
| } | |
| // ---- LAYER 1: Issue linkage ---- | |
| const issuePattern = /(?:closes?|fixes?|resolves?)\s+#(\d+)/gi; | |
| const issueMatches = [...prBody.matchAll(issuePattern)]; | |
| const linkedIssueNumbers = [...new Set(issueMatches.map(m => parseInt(m[1])))]; | |
| if (linkedIssueNumbers.length === 0) { | |
| addCheck('Issue linkage', false, | |
| 'No linked issues found. PR must contain "Closes #N", "Fixes #N", or "Resolves #N".'); | |
| audit.verdict = 'FAIL'; | |
| const auditComment = formatAuditComment(audit); | |
| await postAuditComment(auditComment); | |
| core.setFailed('Phase gate: No linked issues'); | |
| return; | |
| } | |
| addCheck('Issue linkage', true, `Linked issues: ${linkedIssueNumbers.map(n => '#' + n).join(', ')}`); | |
| // ---- Fetch linked issues ---- | |
| const linkedIssues = []; | |
| for (const num of linkedIssueNumbers) { | |
| try { | |
| const issue = await withRetry(() => | |
| github.rest.issues.get({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: num, | |
| }), | |
| `Fetch issue #${num}` | |
| ); | |
| linkedIssues.push(issue.data); | |
| } catch (err) { | |
| addCheck('Issue fetch', false, `Failed to fetch #${num}: ${err.message}`); | |
| } | |
| } | |
| if (linkedIssues.length === 0) { | |
| addCheck('Issue fetch', false, 'Could not fetch any linked issues'); | |
| audit.verdict = 'FAIL'; | |
| const auditComment = formatAuditComment(audit); | |
| await postAuditComment(auditComment); | |
| core.setFailed('Phase gate: Failed to fetch linked issues'); | |
| return; | |
| } | |
| // ---- LAYER 2: Milestone check ---- | |
| const issuesWithMilestones = linkedIssues.filter(i => i.milestone); | |
| const issuesWithoutMilestones = linkedIssues.filter(i => !i.milestone); | |
| if (issuesWithoutMilestones.length > 0) { | |
| const nums = issuesWithoutMilestones.map(i => '#' + i.number).join(', '); | |
| addCheck('Milestone assignment', false, | |
| `Issues without milestones: ${nums}. Every issue must be in a phase milestone.`); | |
| audit.verdict = 'FAIL'; | |
| const auditComment = formatAuditComment(audit); | |
| await postAuditComment(auditComment); | |
| core.setFailed(`Phase gate: Issues ${nums} have no milestone`); | |
| return; | |
| } | |
| // Validate milestone names match config | |
| const milestoneNames = [...new Set(issuesWithMilestones.map(i => i.milestone.title))]; | |
| const unknownMilestones = milestoneNames.filter(m => !phaseConfig[m]); | |
| if (unknownMilestones.length > 0) { | |
| addCheck('Milestone validation', false, | |
| `Unknown milestones: ${unknownMilestones.join(', ')}. Must match a phase in phase-config.yml.`); | |
| audit.verdict = 'FAIL'; | |
| const auditComment = formatAuditComment(audit); | |
| await postAuditComment(auditComment); | |
| core.setFailed(`Phase gate: Unknown milestones: ${unknownMilestones.join(', ')}`); | |
| return; | |
| } | |
| addCheck('Milestone assignment', true, `All issues in known phases: ${milestoneNames.join(', ')}`); | |
| // ---- LAYER 3: Phase prerequisite check ---- | |
| const allMilestones = await withRetry(() => | |
| github.rest.issues.listMilestones({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| state: 'all', | |
| per_page: 100, | |
| }), | |
| 'Fetch all milestones' | |
| ); | |
| const milestoneMap = {}; | |
| for (const ms of allMilestones.data) { | |
| milestoneMap[ms.title] = ms; | |
| } | |
| let allPrereqsMet = true; | |
| const prereqDetails = []; | |
| for (const phaseName of milestoneNames) { | |
| const phase = phaseConfig[phaseName]; | |
| const prereqs = phase.prerequisites || []; | |
| if (prereqs.length === 0) { | |
| prereqDetails.push(`**${phaseName}**: No prerequisites (✅)`); | |
| continue; | |
| } | |
| for (const prereqName of prereqs) { | |
| const prereqMs = milestoneMap[prereqName]; | |
| if (!prereqMs) { | |
| prereqDetails.push(`**${prereqName}**: Milestone not found (❌)`); | |
| allPrereqsMet = false; | |
| continue; | |
| } | |
| const total = prereqMs.open_issues + prereqMs.closed_issues; | |
| if (total === 0) { | |
| prereqDetails.push(`**${prereqName}**: Empty milestone — no tasks defined (❌)`); | |
| allPrereqsMet = false; | |
| continue; | |
| } | |
| if (prereqMs.open_issues > 0) { | |
| const pct = Math.round((prereqMs.closed_issues / total) * 100); | |
| prereqDetails.push( | |
| `**${prereqName}**: ${prereqMs.open_issues} open of ${total} (${pct}% done) (❌)` | |
| ); | |
| allPrereqsMet = false; | |
| } else { | |
| prereqDetails.push(`**${prereqName}**: ${total}/${total} complete (✅)`); | |
| } | |
| } | |
| } | |
| addCheck('Phase prerequisites', allPrereqsMet, | |
| prereqDetails.join(' | ')); | |
| // ---- VERDICT ---- | |
| if (allPrereqsMet) { | |
| audit.verdict = 'PASS'; | |
| const auditComment = formatAuditComment(audit); | |
| await postAuditComment(auditComment); | |
| core.info('✅ Phase gate: All prerequisites met. Merge allowed.'); | |
| } else { | |
| audit.verdict = 'FAIL'; | |
| const auditComment = formatAuditComment(audit); | |
| await postAuditComment(auditComment); | |
| core.setFailed('Phase gate: Prerequisites not met. See PR comment for details.'); | |
| } | |
| // ---- AUDIT HELPERS ---- | |
| function formatAuditComment(audit) { | |
| const icon = audit.verdict === 'PASS' ? '✅' : | |
| audit.verdict === 'BYPASS' ? '⚠️' : '🚫'; | |
| const color = audit.verdict === 'PASS' ? 'green' : | |
| audit.verdict === 'BYPASS' ? 'orange' : 'red'; | |
| let body = `## 🔒 Phase Gate Enforcement — ${icon} ${audit.verdict}\n\n`; | |
| body += `| Check | Result | Detail |\n|-------|--------|--------|\n`; | |
| for (const check of audit.checks) { | |
| const detail = check.detail.length > 120 | |
| ? check.detail.slice(0, 117) + '...' | |
| : check.detail; | |
| body += `| ${check.name} | ${check.icon} | ${detail} |\n`; | |
| } | |
| body += `\n**Verdict:** ${audit.verdict}`; | |
| if (audit.bypass_reason) { | |
| body += ` — Reason: "${audit.bypass_reason.slice(0, 200)}"`; | |
| } | |
| body += `\n**Timestamp:** ${audit.timestamp}`; | |
| body += `\n**Run:** [View workflow run](${audit.run_url})`; | |
| if (audit.verdict === 'FAIL') { | |
| body += `\n\n---\n`; | |
| body += `> **How to fix:** Ensure all prerequisite phases are complete, `; | |
| body += `or add \`emergency:bypass\` label with a \`## Bypass Reason\` section in the PR body.\n`; | |
| } | |
| if (audit.verdict === 'BYPASS') { | |
| body += `\n\n---\n`; | |
| body += `> ⚠️ **This merge bypassed phase gate enforcement.** `; | |
| body += `The bypass reason has been recorded for audit purposes.\n`; | |
| } | |
| return body; | |
| } | |
| async function postAuditComment(body) { | |
| // Find existing enforcement comment and update it (don't spam) | |
| const marker = '## 🔒 Phase Gate Enforcement'; | |
| try { | |
| const comments = await withRetry(() => | |
| github.rest.issues.listComments({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: pr.number, | |
| per_page: 100, | |
| }), | |
| 'Fetch PR comments' | |
| ); | |
| const existing = comments.data.find(c => | |
| c.user.login === 'github-actions[bot]' && | |
| c.body.startsWith(marker) | |
| ); | |
| if (existing) { | |
| await withRetry(() => | |
| github.rest.issues.updateComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| comment_id: existing.id, | |
| body: body, | |
| }), | |
| 'Update audit comment' | |
| ); | |
| } else { | |
| await withRetry(() => | |
| github.rest.issues.createComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: pr.number, | |
| body: body, | |
| }), | |
| 'Create audit comment' | |
| ); | |
| } | |
| } catch (err) { | |
| // Audit comment failure does NOT block the enforcement decision. | |
| // The status check result is what matters for merge blocking. | |
| core.warning(`Failed to post audit comment: ${err.message}`); | |
| } | |
| } |