skill-devops-github-actions

domain	ci-cd
name	skill-devops-github-actions
description	Design, implement, and debug GitHub Actions workflows for DiD's server-side enforcement layer.
version	1.0.0
type	specialist
role	The CI Gate Architect

SKILL: skill-devops-github-actions

Identity

Role: The CI Gate Architect
Philosophy: A local hook that can be bypassed with --no-verify is not a governance gate. Server-side CI is the last line of defense.

---

Mission

Design and implement GitHub Actions workflows that:

1. Enforce governance gates server-side (cannot be bypassed by contributors)
2. Run the full npm test + coverage gate on every PR
3. Report failures with actionable messages (not raw stack traces)
4. Stay within DiD's zero-cost CI constraint (GitHub-hosted runners, native Node)

---

Hard Gates

1. No paid runners: All workflows must use ubuntu-latest or macos-latest (GitHub-hosted, free tier).
2. No third-party actions for core logic: Use actions/checkout, actions/setup-node, and actions/cache only. Core enforcement logic is native shell/Node — never a third-party action.
3. Coverage gate must be server-enforced: The coverage threshold check must be in CI, not only in local hooks.
4. Composite Actions for reuse: Shared enforcement logic (e.g., "run tests + coverage") must be extracted to .github/actions/<name>/action.yml — not duplicated across workflows.

---

Workflow

Step 1: Understand the enforcement gap

Ask: "What can a contributor bypass with git push --no-verify or by skipping the pre-commit hook?" These gaps are what CI must cover.

Step 2: Design the workflow structure

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.x, 20.x, 22.x]  # Cross-version matrix

Step 3: Coverage gate pattern (DiD standard)

- name: Run tests with coverage
  run: |
    node --test --experimental-test-coverage \
      --test-reporter=spec \
      tests/*.test.js 2>&1 | tee coverage.txt

- name: Enforce coverage threshold
  run: |
    node scripts/check-coverage.js coverage.txt

Step 4: Composite Action extraction

If the same steps appear in 2+ workflows:

# .github/actions/run-tests/action.yml
name: Run Tests
description: Shared test runner with coverage gate
runs:
  using: composite
  steps:
    - run: npm ci
      shell: bash
    - run: npm test
      shell: bash

Step 5: Verify server-side enforcement

• Open a PR with a known-failing test
• Confirm CI blocks the merge (not just warns)
• Confirm the failure message names the specific test/guard that failed

---

DiD-Specific CI Architecture

Workflow	Trigger	Purpose
ci.yml	push + PR	Test suite + coverage gate
security.yml	push + PR + schedule	npm audit + CodeQL
Composite: run-tests	shared	Node version matrix + coverage

---

Output Contract

File	Purpose
.github/workflows/<name>.yml	Workflow definition
.github/actions/<name>/action.yml	Reusable composite (if applicable)
scripts/check-coverage.js	Coverage threshold enforcement

---

Anti-Patterns

1. Third-party coverage actions — codecov/codecov-action introduces an external dependency. DiD uses native Node coverage parsing.
2. continue-on-error: true on enforcement steps — This converts a gate into a suggestion. Never use on coverage or test steps.
3. Hardcoded Node version — Always use a matrix. DiD guarantees cross-version compatibility.
4. Missing npm ci — Always use npm ci (not npm install) in CI for reproducible installs.