@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/skills/shared/external/github-actions-templates/SKILL.md

@@ -1,334 +1,192 @@
 ---
 name: github-actions-templates
-description: "Production-ready GitHub Actions workflow patterns for testing, building, and deploying applications. Use when a GitHub Actions workflow has to be written or hardened."
-risk: critical
-source: community
-date_added: "2026-02-27"
+description: "Authoring GitHub Actions workflows: triggers, matrices, caching, concurrency, least-privilege permissions, SHA pinning, OIDC, reusable workflows, composite actions, Xcode runners. Use when writing or hardening a workflow file."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
+  not-for: ci-cd-pipelines
 ---
 
-# GitHub Actions Templates
+# GitHub Actions Authoring
 
-Production-ready GitHub Actions workflow patterns for testing, building, and deploying applications.
+This skill covers the YAML itself: how a workflow is triggered, how jobs are
+wired, and how it is kept fast and safe. Deciding what a delivery pipeline
+should contain (stages, promotion, rollback) is `ci-cd-pipelines`; building the
+container image is `docker-expert`.
 
-## Do not use this skill when
+## Workflow skeleton
 
-- The task is unrelated to github actions templates
-- You need a different domain or tool outside this scope
-
-## Instructions
-
-- Clarify goals, constraints, and required inputs.
-- Apply relevant best practices and validate outcomes.
-- Provide actionable steps and verification.
-
-## Purpose
-
-Create efficient, secure GitHub Actions workflows for continuous integration and deployment across various tech stacks.
-
-## Use this skill when
-
-- Automate testing and deployment
-- Build Docker images and push to registries
-- Deploy to Kubernetes clusters
-- Run security scans
-- Implement matrix builds for multiple environments
-
-## Common Workflow Patterns
-
-### Pattern 1: Test Workflow
+Start every workflow from the same frame and add to it:
 
 ```yaml
-name: Test
+name: products-api
 
 on:
-  push:
-    branches: [ main, develop ]
   pull_request:
-    branches: [ main ]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x]
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-
-    - name: Install dependencies
-      run: npm ci
-
-    - name: Run linter
-      run: npm run lint
-
-    - name: Run tests
-      run: npm test
-
-    - name: Upload coverage
-      uses: codecov/codecov-action@v3
-      with:
-        files: ./coverage/lcov.info
-```
-
-### Pattern 2: Build and Push Docker Image
-
-```yaml
-name: Build and Push
-
-on:
+    paths: ["services/products/**", ".github/workflows/products-api.yml"]
   push:
-    branches: [ main ]
-    tags: [ 'v*' ]
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}
+    branches: [main]
+  workflow_dispatch:
 
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
+permissions:
+  contents: read
 
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Log in to Container Registry
-      uses: docker/login-action@v3
-      with:
-        registry: ${{ env.REGISTRY }}
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Extract metadata
-      id: meta
-      uses: docker/metadata-action@v5
-      with:
-        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-        tags: |
-          type=ref,event=branch
-          type=ref,event=pr
-          type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-
-    - name: Build and push
-      uses: docker/build-push-action@v5
-      with:
-        context: .
-        push: true
-        tags: ${{ steps.meta.outputs.tags }}
-        labels: ${{ steps.meta.outputs.labels }}
-        cache-from: type=gha
-        cache-to: type=gha,mode=max
-```
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
-### Pattern 3: Deploy to Kubernetes
-
-```yaml
-name: Deploy to Kubernetes
-
-on:
-  push:
-    branches: [ main ]
+defaults:
+  run:
+    shell: bash
+    working-directory: services/products
 
 jobs:
-  deploy:
-    runs-on: ubuntu-latest
-
+  test:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
     steps:
-    - uses: actions/checkout@v4
-
-    - name: Configure AWS credentials
-      uses: aws-actions/configure-aws-credentials@v4
-      with:
-        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-        aws-region: us-west-2
-
-    - name: Update kubeconfig
-      run: |
-        aws eks update-kubeconfig --name production-cluster --region us-west-2
-
-    - name: Deploy to Kubernetes
-      run: |
-        kubectl apply -f k8s/
-        kubectl rollout status deployment/my-app -n production
-        kubectl get services -n production
-
-    - name: Verify deployment
-      run: |
-        kubectl get pods -n production
-        kubectl describe deployment my-app -n production
+      - uses: actions/checkout@<full-40-char-sha> # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@<full-40-char-sha> # v4.1.0
+        with:
+          node-version-file: services/products/.nvmrc
+          cache: npm
+          cache-dependency-path: services/products/package-lock.json
+      - run: npm ci
+      - run: npm test
 ```
 
-### Pattern 4: Matrix Build
+Why each piece is there:
+
+- `permissions: contents: read` at the top makes the token read-only; jobs that
+  need more ask for it themselves.
+- `concurrency` cancels superseded PR runs but lets every push to `main` finish.
+- `timeout-minutes` stops a hung job before it burns the default six hours.
+- `paths` keeps unrelated changes from running this workflow. A required status
+  check on a path-filtered workflow blocks PRs that never trigger it; gate on
+  an always-running summary job instead.
+
+## Security rules
+
+1. **Pin third-party actions to a full commit SHA** and keep the tag in a
+   comment. Tags are mutable. Dependabot (`package-ecosystem: github-actions`)
+   updates SHA pins.
+2. **Grant permissions per job.** Typical needs:
+
+   | Job does | Needs |
+   |----------|-------|
+   | comment on a PR | `pull-requests: write` |
+   | push a tag or release | `contents: write` |
+   | publish to GHCR | `packages: write` |
+   | OIDC to a cloud | `id-token: write` |
+   | attestations | `id-token: write`, `attestations: write` |
+
+3. **Never interpolate untrusted input into `run:`.** A PR title or branch name
+   can contain shell. Pass it through `env:` and quote it:
+
+   ```yaml
+   - env:
+       TITLE: ${{ github.event.pull_request.title }}
+     run: echo "Checking: $TITLE"
+   ```
+
+4. **`pull_request_target` runs with secrets on fork PRs.** Do not check out
+   and execute the PR head under it. Use `pull_request` for untrusted code and
+   a separate `workflow_run` job for privileged follow-ups.
+5. **Prefer OIDC to long-lived cloud keys.** The runner exchanges a short-lived
+   token scoped to repo, branch or environment.
+
+   ```yaml
+   deploy:
+     permissions:
+       id-token: write
+       contents: read
+     environment: production
+     steps:
+       - uses: aws-actions/configure-aws-credentials@<sha> # v4
+         with:
+           role-to-assume: arn:aws:iam::123456789012:role/products-deploy
+           aws-region: eu-central-1
+   ```
+
+   The cloud trust policy should match the `sub` claim, for example
+   `repo:acme/shop:environment:production`, not just the repository.
+6. **Keep secrets in environments** when only the deploy job needs them, so
+   test jobs cannot read them.
+
+## Matrices
 
 ```yaml
-name: Matrix Build
-
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.9', '3.10', '3.11', '3.12']
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt
-
-    - name: Run tests
-      run: pytest
+strategy:
+  fail-fast: false
+  matrix:
+    node: [20, 22]
+    os: [ubuntu-24.04]
+    include:
+      - node: 22
+        os: macos-15
+    exclude:
+      - node: 20
+        os: macos-15
 ```
 
-## Workflow Best Practices
+- `fail-fast: false` shows every failing combination instead of the first.
+- `max-parallel` protects shared resources such as a test database.
+- A dynamic matrix comes from a previous job's output with `fromJSON(...)`,
+  useful for "test only the packages that changed" in a monorepo.
 
-1. **Use specific action versions** (@v4, not @latest)
-2. **Cache dependencies** to speed up builds
-3. **Use secrets** for sensitive data
-4. **Implement status checks** on PRs
-5. **Use matrix builds** for multi-version testing
-6. **Set appropriate permissions**
-7. **Use reusable workflows** for common patterns
-8. **Implement approval gates** for production
-9. **Add notification steps** for failures
-10. **Use self-hosted runners** for sensitive workloads
+## Caching
 
-## Reusable Workflows
+- Use the setup action's built-in `cache:` first (npm, pnpm, yarn, pip, poetry,
+  gradle, maven, go).
+- Otherwise `actions/cache` with a key that hashes the lockfile and a
+  `restore-keys` prefix for partial hits.
+- Caches are scoped per branch with fallback to the default branch; a PR can
+  read `main`'s cache but not write to it.
+- Docker layers: `docker/build-push-action` with `cache-from: type=gha` and
+  `cache-to: type=gha,mode=max`.
 
-```yaml
-# .github/workflows/reusable-test.yml
-name: Reusable Test Workflow
+## Environments and approvals
 
-on:
-  workflow_call:
-    inputs:
-      node-version:
-        required: true
-        type: string
-    secrets:
-      NPM_TOKEN:
-        required: true
+An `environment:` on a job applies its protection rules: required reviewers,
+wait timer, allowed branches, and environment-scoped secrets and variables.
+Model staging and production as separate environments and let the production
+job `needs:` the staging one.
 
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: ${{ inputs.node-version }}
-    - run: npm ci
-    - run: npm test
-```
+## Provenance
 
-**Use reusable workflow:**
 ```yaml
-jobs:
-  call-test:
-    uses: ./.github/workflows/reusable-test.yml
+permissions:
+  id-token: write
+  attestations: write
+  contents: read
+steps:
+  - uses: actions/attest-build-provenance@<sha>
     with:
-      node-version: '20.x'
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      subject-path: dist/products-api.tar.gz
 ```
 
-## Security Scanning
+Consumers verify with `gh attestation verify <file> --repo acme/shop`.
 
-```yaml
-name: Security Scan
+## Debugging a workflow
 
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
+- Re-run with debug logging (`ACTIONS_STEP_DEBUG` secret or the re-run option).
+- Lint locally with `actionlint`; it catches expression and shell errors.
+- `act` runs many workflows locally, but not macOS jobs or OIDC.
+- Expressions in `if:` without `${{ }}` are evaluated anyway; a string that
+  starts with `!` must be wrapped in `${{ }}`.
 
-jobs:
-  security:
-    runs-on: ubuntu-latest
+## Review checklist
 
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Run Trivy vulnerability scanner
-      uses: aquasecurity/trivy-action@master
-      with:
-        scan-type: 'fs'
-        scan-ref: '.'
-        format: 'sarif'
-        output: 'trivy-results.sarif'
-
-    - name: Upload Trivy results to GitHub Security
-      uses: github/codeql-action/upload-sarif@v2
-      with:
-        sarif_file: 'trivy-results.sarif'
-
-    - name: Run Snyk Security Scan
-      uses: snyk/actions/node@master
-      env:
-        SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
-```
-
-## Deployment with Approvals
-
-```yaml
-name: Deploy to Production
-
-on:
-  push:
-    tags: [ 'v*' ]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment:
-      name: production
-      url: https://app.example.com
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Deploy application
-      run: |
-        echo "Deploying to production..."
-        # Deployment commands here
-
-    - name: Notify Slack
-      if: success()
-      uses: slackapi/slack-github-action@v1
-      with:
-        webhook-url: ${{ secrets.SLACK_WEBHOOK }}
-        payload: |
-          {
-            "text": "Deployment to production completed successfully!"
-          }
-```
+- Top-level `permissions` is read-only; every write scope is job-level and used.
+- Every non-GitHub action is SHA-pinned.
+- No `${{ github.event.* }}` inside a `run:` script body.
+- Each job has `timeout-minutes`; PR runs cancel on new pushes.
+- Cloud access goes through OIDC with a subject-restricted trust policy.
+- Deploy jobs use an environment with reviewers.
 
-## Related Skills
+## References
 
-- `gitlab-ci-patterns` - For GitLab CI workflows
-- `deployment-pipeline-design` - For pipeline architecture
-- `secrets-management` - For secrets handling
+- `references/patterns.md`: reusable workflows versus composite actions, passing outputs and artifacts between jobs, and Xcode builds on macOS runners. Load it when the task reaches those topics.

package/pipeline/skills/shared/external/github-actions-templates/references/patterns.md

@@ -0,0 +1,96 @@
+# GitHub Actions patterns
+
+Loaded on demand from `../SKILL.md`.
+
+## Sharing logic
+
+| Need | Use |
+|------|-----|
+| A few steps repeated across jobs | composite action in `.github/actions/<name>/action.yml` |
+| Whole jobs repeated across repos | reusable workflow with `on: workflow_call` |
+| Logic that needs its own runtime or tests | JavaScript or container action in its own repo |
+
+Reusable workflow:
+
+```yaml
+# .github/workflows/node-service.yml
+on:
+  workflow_call:
+    inputs:
+      path: { type: string, required: true }
+    secrets:
+      NPM_TOKEN: { required: false }
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    defaults: { run: { working-directory: "${{ inputs.path }}" } }
+    steps:
+      - uses: actions/checkout@<sha>
+      - run: npm ci && npm test
+```
+
+```yaml
+# caller
+jobs:
+  notes-service:
+    uses: acme/platform/.github/workflows/node-service.yml@<sha>
+    with: { path: services/notes }
+    secrets: inherit
+```
+
+Composite action:
+
+```yaml
+# .github/actions/setup-pnpm/action.yml
+name: setup-pnpm
+inputs:
+  node-version: { default: "22" }
+runs:
+  using: composite
+  steps:
+    - uses: pnpm/action-setup@<sha>
+    - uses: actions/setup-node@<sha>
+      with: { node-version: "${{ inputs.node-version }}", cache: pnpm }
+    - run: pnpm install --frozen-lockfile
+      shell: bash
+```
+
+Composite steps must declare `shell:` on every `run`.
+
+## Passing data
+
+- Step to step: `echo "version=$VERSION" >> "$GITHUB_OUTPUT"`, read as
+  `steps.<id>.outputs.version`.
+- Job to job: declare `outputs:` on the job and read `needs.<job>.outputs.x`.
+- Files: `actions/upload-artifact` / `download-artifact` (v4 artifacts are
+  immutable per name; use unique names per matrix leg).
+- Summary for humans: append Markdown to `$GITHUB_STEP_SUMMARY`.
+
+## Xcode on macOS runners
+
+```yaml
+ios:
+  runs-on: macos-15
+  timeout-minutes: 45
+  steps:
+    - uses: actions/checkout@<sha>
+    - run: sudo xcode-select -s /Applications/Xcode_16.4.app
+    - uses: actions/cache@<sha>
+      with:
+        path: ~/Library/Developer/Xcode/DerivedData/**/SourcePackages
+        key: spm-${{ hashFiles('**/Package.resolved') }}
+    - run: |
+        set -o pipefail
+        xcodebuild test \
+          -scheme Notes -destination 'platform=iOS Simulator,name=iPhone 16' \
+          -resultBundlePath TestResults.xcresult | xcbeautify
+    - if: failure()
+      uses: actions/upload-artifact@<sha>
+      with: { name: xcresult, path: TestResults.xcresult }
+```
+
+- macOS minutes cost several times Linux minutes; run lint and unit tests of
+  pure packages on Linux where possible.
+- Check the runner image's installed Xcode list before selecting a version.
+- Import signing certificates into a temporary keychain created in the job and
+  delete it in an `if: always()` step.

package/pipeline/skills/shared/external/healthkit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: healthkit
 description: "Read, write, and query Apple Health data using HealthKit. Covers HKHealthStore authorization, sample queries, statistics queries, statistics collection queries for charts, saving HKQuantitySample data, background delivery, workout sessions with HKWorkoutSession and HKLiveWorkoutBuilder, HKUnit, and HKQuantityTypeIdentifier values. Use when integrating with Apple Health, displaying health metrics, recording workouts, or enabling background health data delivery."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # HealthKit