@hybridlabor-api/aos 4.8.0 → 4.9.0

package/skills/global_config/github-actions-validator/references/modern_features.md

@@ -0,0 +1,384 @@
+# Modern GitHub Actions Features Reference
+
+This reference covers validation of modern GitHub Actions features including reusable workflows, attestations, OIDC authentication, and more.
+
+## Reusable Workflows
+
+### Validation Points
+- `workflow_call` trigger configuration
+- Required and optional inputs with correct types
+- Secrets declaration and usage
+- Outputs definition
+
+### Example
+
+```yaml
+# Reusable workflow (.github/workflows/reusable-deploy.yml)
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+      deploy-version:
+        required: false
+        type: string
+        default: 'latest'
+    secrets:
+      deploy-token:
+        required: true
+    outputs:
+      deployment-url:
+        description: "The URL of the deployment"
+        value: ${{ jobs.deploy.outputs.url }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    outputs:
+      url: ${{ steps.deploy.outputs.url }}
+    steps:
+      - name: Deploy
+        id: deploy
+        run: echo "url=https://example.com" >> $GITHUB_OUTPUT
+```
+
+### Common Errors
+- Incorrect input types (string, number, boolean)
+- Missing required secrets
+- Invalid output references
+
+### Workflow Limits (November 2025)
+
+GitHub Actions increased reusable workflow limits:
+- **Nested workflows**: Up to 10 levels (previously 4)
+- **Total workflows per run**: Up to 50 workflows (previously 20)
+
+This enables complex workflow compositions and better code reuse.
+
+---
+
+## SBOM and Build Provenance Attestations
+
+### Validation Points
+- Correct permissions (`id-token: write`, `attestations: write`)
+- Valid artifact paths
+- Proper attestation action usage
+
+### Example
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+  attestations: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Build artifact
+        run: |
+          mkdir -p dist
+          tar -czvf dist/app.tar.gz ./src
+
+      - name: Generate SBOM
+        run: |
+          # Generate SPDX SBOM
+          syft ./src -o spdx-json > sbom.spdx.json
+
+      - uses: actions/attest-sbom@v3
+        with:
+          subject-path: '${{ github.workspace }}/dist/*.tar.gz'
+          sbom-path: '${{ github.workspace }}/sbom.spdx.json'
+
+      - uses: actions/attest-build-provenance@v3
+        with:
+          subject-path: '${{ github.workspace }}/dist/*.tar.gz'
+```
+
+### Common Errors
+- Missing required permissions
+- Invalid subject-path glob patterns
+- Incorrect SBOM format
+
+---
+
+## OIDC Authentication
+
+### Validation Points
+- Correct permissions (`id-token: write`)
+- Valid audience claims
+- Proper OIDC provider configuration
+- Token claim validation in receiving systems
+
+### Available Token Claims (November 2025)
+
+| Claim | Description |
+|-------|-------------|
+| `repository` | Repository name |
+| `ref` | Git ref (branch/tag) |
+| `sha` | Commit SHA |
+| `workflow` | Workflow name |
+| `run_id` | Workflow run ID |
+| `run_attempt` | Attempt number |
+| `check_run_id` | **NEW** - Specific check run ID for the job |
+| `actor` | User who triggered the workflow |
+| `environment` | Deployment environment (if applicable) |
+
+### Example: AWS OIDC
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
+          aws-region: us-east-1
+          # Token now includes check_run_id for granular tracking
+
+      - name: Deploy to AWS
+        run: aws s3 sync ./build s3://my-bucket/
+```
+
+### AWS IAM Policy with check_run_id
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Effect": "Allow",
+    "Principal": {
+      "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
+    },
+    "Action": "sts:AssumeRoleWithWebIdentity",
+    "Condition": {
+      "StringEquals": {
+        "token.actions.githubusercontent.com:sub": "repo:org/repo:ref:refs/heads/main",
+        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+      },
+      "StringLike": {
+        "token.actions.githubusercontent.com:check_run_id": "*"
+      }
+    }
+  }]
+}
+```
+
+### Benefits of check_run_id
+- **Fine-grained access control**: Trace tokens to exact job and compute
+- **Improved auditability**: Track which specific check run made API calls
+- **Least-privilege policies**: Attribute-based access control without enumerating repositories
+- **Faster revocation**: Reduce secret exposure risk
+
+---
+
+## Deployment Environments
+
+### Validation Points
+- Environment name configuration
+- Protection rules compatibility
+- Required reviewers setup
+- Environment variables and secrets scope
+
+### Example
+
+```yaml
+jobs:
+  deploy-staging:
+    runs-on: ubuntu-latest
+    environment:
+      name: staging
+      url: https://staging.example.com
+    steps:
+      - uses: actions/checkout@v6
+      - run: ./deploy.sh staging
+
+  deploy-production:
+    runs-on: ubuntu-latest
+    needs: deploy-staging
+    environment:
+      name: production
+      url: https://prod.example.com
+    steps:
+      - uses: actions/checkout@v6
+      - run: ./deploy.sh production
+```
+
+### Common Errors
+- Undefined environment names
+- Missing URL for environment tracking
+- Incorrect environment variable scope
+
+---
+
+## Job Summaries
+
+### Validation Points
+- Correct usage of `$GITHUB_STEP_SUMMARY`
+- Valid Markdown formatting
+- Proper escaping of dynamic content
+
+### Example
+
+```yaml
+steps:
+  - name: Run tests
+    id: tests
+    run: |
+      # Run tests and capture results
+      npm test 2>&1 | tee test-output.txt
+      PASSED=$(grep -c "PASS" test-output.txt || echo 0)
+      FAILED=$(grep -c "FAIL" test-output.txt || echo 0)
+      echo "passed=$PASSED" >> $GITHUB_OUTPUT
+      echo "failed=$FAILED" >> $GITHUB_OUTPUT
+
+  - name: Generate summary
+    run: |
+      echo "## Test Results" >> $GITHUB_STEP_SUMMARY
+      echo "" >> $GITHUB_STEP_SUMMARY
+      echo "| Status | Count |" >> $GITHUB_STEP_SUMMARY
+      echo "|--------|-------|" >> $GITHUB_STEP_SUMMARY
+      echo "| Passed | ${{ steps.tests.outputs.passed }} |" >> $GITHUB_STEP_SUMMARY
+      echo "| Failed | ${{ steps.tests.outputs.failed }} |" >> $GITHUB_STEP_SUMMARY
+```
+
+**Note:** Job summaries are runtime features - actionlint validates script syntax but not summary content.
+
+---
+
+## Container Jobs
+
+### Validation Points
+- Valid container image references
+- Correct volume mounts
+- Environment variable configuration
+- Service container networking
+
+### Example
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: node:24
+      env:
+        NODE_ENV: test
+      volumes:
+        - /data:/data
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: testdb
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        env:
+          DATABASE_URL: postgres://postgres:postgres@postgres:5432/testdb
+          REDIS_URL: redis://redis:6379
+        run: npm test
+```
+
+### Common Errors
+- Invalid image tags
+- Incorrect volume mount syntax
+- Service container networking issues
+- Missing health checks for services
+
+---
+
+## Matrix Strategies
+
+### Validation Points
+- Matrix values must be arrays
+- Valid matrix variable references
+- Proper include/exclude syntax
+
+### Example
+
+```yaml
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node: [20, 22, 24]
+        exclude:
+          - os: macos-latest
+            node: 20
+        include:
+          - os: ubuntu-latest
+            node: 24
+            experimental: true
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm test
+```
+
+---
+
+## Concurrency Control
+
+### Validation Points
+- Valid concurrency group names
+- Proper cancel-in-progress usage
+
+### Example
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: npm ci && npm run build
+```
+
+This prevents redundant runs while protecting main branch runs from cancellation.

package/skills/global_config/github-actions-validator/references/runners.md

@@ -0,0 +1,317 @@
+# GitHub-Hosted Runners Reference (2025)
+
+This reference covers all GitHub-hosted runner types, including recent additions and deprecations.
+
+## Standard Runner Labels
+
+### Ubuntu
+
+```yaml
+runs-on: ubuntu-latest      # Ubuntu 24.04 (default)
+runs-on: ubuntu-24.04       # Ubuntu 24.04
+runs-on: ubuntu-22.04       # Ubuntu 22.04
+runs-on: ubuntu-20.04       # Ubuntu 20.04
+```
+
+### Windows
+
+```yaml
+runs-on: windows-latest     # Windows Server 2022 (default)
+runs-on: windows-2025       # Windows Server 2025 (NEW)
+runs-on: windows-2022       # Windows Server 2022
+runs-on: windows-2019       # Windows Server 2019
+```
+
+### macOS
+
+```yaml
+runs-on: macos-latest       # macOS 15 (as of Aug 2025)
+runs-on: macos-15           # macOS 15 Sequoia (Apple Silicon)
+runs-on: macos-14           # macOS 14 Sonoma (Apple Silicon)
+runs-on: macos-26           # macOS 26 (PREVIEW)
+```
+
+---
+
+## macOS Runner Updates and Deprecations
+
+### Current Status
+
+| Label | Status | Architecture | Notes |
+|-------|--------|--------------|-------|
+| `macos-latest` | **Active** | ARM64 (Apple Silicon) | Points to macOS 15 |
+| `macos-15` | **Active** | ARM64 (Apple Silicon) | M1/M2/M3 |
+| `macos-14` | **Active** | ARM64 (Apple Silicon) | M1/M2 |
+| `macos-26` | **Preview** | ARM64 (Apple Silicon) | Beta |
+| `macos-13` | **RETIRED** | Intel x86_64 | Retired November 14, 2025 |
+| `macos-12` | **RETIRED** | Intel x86_64 | Retired |
+
+### Intel-Specific Labels (Long-term Deprecated)
+
+```yaml
+runs-on: macos-15-intel     # Intel x86_64 (NEW but deprecated long-term)
+runs-on: macos-14-large     # Intel x86_64
+runs-on: macos-15-large     # Intel x86_64
+```
+
+**Important:** Apple Silicon (ARM64) will be required after Fall 2027. Plan migration now.
+
+### Migration Example
+
+```yaml
+jobs:
+  build:
+    # BAD - macos-13 retired Nov 14, 2025 (WILL FAIL)
+    # runs-on: macos-13
+
+    # GOOD - Use macos-15 or macos-latest
+    runs-on: macos-15
+
+    steps:
+      - uses: actions/checkout@v6
+      - run: ./build.sh
+```
+
+---
+
+## ARM64 Runners
+
+### Availability
+- **Generally available** as of August 2025
+- **Free** for public repositories
+- **Private repositories** require GitHub Enterprise Cloud plan
+
+### Labels
+
+```yaml
+runs-on: ubuntu-latest-arm64    # Free for public repos
+runs-on: ubuntu-24.04-arm64
+runs-on: windows-latest-arm64   # ARM Windows
+```
+
+### Example
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest-arm64  # Free for public repos
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build on ARM64
+        run: |
+          uname -m  # Should output: aarch64
+          ./build.sh
+```
+
+### Specifications
+- 4 vCPU ARM64 processors
+- Available for Linux and Windows
+- Native ARM execution (no virtualization needed)
+- Ideal for multi-architecture builds
+
+### Common Validation Issues
+- Using ARM64 runners in private repos without Enterprise Cloud
+- Assuming all community actions work on ARM64
+- Not testing ARM-specific compilation issues
+
+---
+
+## GPU Runners
+
+### Availability
+- **Generally available** for Windows and Linux
+- Requires **Team** or **Enterprise Cloud** plan
+
+### Labels
+
+```yaml
+runs-on: gpu-t4-4-core      # NVIDIA Tesla T4
+```
+
+### Specifications
+- **GPU:** NVIDIA Tesla T4 with 16GB VRAM
+- **CPU:** 4 vCPUs
+- **RAM:** 28GB
+- **Pricing:** $0.07/minute
+
+### Example
+
+```yaml
+jobs:
+  ml-training:
+    runs-on: gpu-t4-4-core
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install ML dependencies
+        run: |
+          pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+          pip install -r requirements.txt
+
+      - name: Train model
+        run: python train.py --use-gpu
+
+      - name: Run inference
+        run: python inference.py
+```
+
+### Use Cases
+- ML model training
+- GPU-accelerated testing
+- CUDA development
+- Image/video processing
+
+### Common Validation Issues
+- Missing CUDA setup
+- Incorrect GPU driver versions
+- Not utilizing GPU in workloads (CPU fallback)
+- Missing GPU-specific dependencies
+
+---
+
+## M2 Pro macOS Runners (Larger Runners)
+
+### Availability
+- **Generally available** with M2 Pro powered runners
+
+### Labels
+
+```yaml
+runs-on: macos-latest-xlarge  # macOS 15, M2 Pro
+runs-on: macos-15-xlarge      # macOS 15, M2 Pro
+runs-on: macos-14-xlarge      # macOS 14, M2 Pro
+```
+
+### Specifications
+- **CPU:** 5-core (vs 3-core standard)
+- **GPU:** 8-core with hardware acceleration (enabled by default)
+- **RAM:** 14GB
+- **Storage:** 14GB
+- **Performance:** Up to 15% faster than M1 runners
+- **Pricing:** $0.16/minute
+
+### Example
+
+```yaml
+jobs:
+  ios-build:
+    runs-on: macos-15-xlarge  # M2 Pro with GPU acceleration
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Xcode
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
+      - name: Build iOS app
+        run: |
+          xcodebuild -workspace App.xcworkspace \
+            -scheme Production \
+            -configuration Release \
+            -archivePath build/App.xcarchive \
+            archive
+
+      - name: Run GPU-accelerated tests
+        run: |
+          # GPU acceleration automatically available
+          xcodebuild test -scheme AppTests
+```
+
+### Benefits
+- GPU hardware acceleration for Metal-based workloads
+- Improved build times for iOS/macOS apps
+- Better performance for Xcode builds
+- Native Apple Silicon performance
+
+---
+
+## Runner Selection Best Practices
+
+### Decision Criteria
+
+1. **Architecture compatibility:** ARM64 vs Intel x86_64
+2. **Cost optimization:** Standard vs larger runners
+3. **GPU requirements:** ML/AI workloads need GPU runners
+4. **Operating system:** Latest versions recommended
+5. **Deprecation timelines:** Avoid retired runners
+6. **Public vs private repos:** ARM64 free only for public repos
+
+### Validation Checklist
+
+```yaml
+# Check these in your workflows:
+- [ ] Using latest runner versions (macos-15, windows-2025, ubuntu-latest)
+- [ ] Not using deprecated runners (macos-13)
+- [ ] Architecture-appropriate runners (ARM64 vs Intel)
+- [ ] GPU runners for ML workloads
+- [ ] Cost-effective runner selection
+- [ ] ARM64 compatibility tested (if using ARM64 runners)
+```
+
+### Cost Comparison
+
+| Runner Type | Pricing | Best For |
+|-------------|---------|----------|
+| Standard (Linux/Windows) | Included | Most workloads |
+| Standard (macOS) | Included | iOS/macOS builds |
+| ARM64 (public repos) | **Free** | Multi-arch builds |
+| ARM64 (private repos) | Enterprise | ARM-native builds |
+| GPU (T4) | $0.07/min | ML/AI workloads |
+| M2 Pro (xlarge) | $0.16/min | Heavy iOS builds |
+
+---
+
+## Multi-Architecture Builds
+
+### Example: Building for Multiple Architectures
+
+```yaml
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            arch: x64
+          - runner: ubuntu-latest-arm64
+            arch: arm64
+
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Build
+        run: |
+          echo "Building for ${{ matrix.arch }}"
+          ./build.sh --arch ${{ matrix.arch }}
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-${{ matrix.arch }}
+          path: dist/
+```
+
+---
+
+## Self-Hosted Runner Configuration
+
+When using self-hosted runners, configure actionlint to recognize custom labels:
+
+```yaml
+# .github/actionlint.yaml
+self-hosted-runner:
+  labels:
+    - my-custom-runner
+    - gpu-runner
+    - arm-runner
+    - on-premises
+```
+
+This prevents actionlint from reporting unknown runner label errors.