Intermediate

# => File: .github/workflows/secrets-context.yml
name: secrets-context # => Workflow identifier shown in the Actions UI

on:
  push: # => Trigger: runs on every push to any branch
    branches: ["main"] # => Narrow to main branch only

jobs:
  deploy:
    runs-on: ubuntu-latest # => Use GitHub-hosted Ubuntu runner

    steps:
      - uses: actions/checkout@v4 # => Check out source code first

      - name: Use a secret value # => Step name shown in the UI
        env:
          # => Map secrets into step-level environment variables
          # => secrets.DEPLOY_TOKEN reads from Settings → Secrets → Actions
          # => The value is masked in logs — GitHub replaces it with ***
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          # => DEPLOY_TOKEN is now available as a regular env var
          # => If secrets.DEPLOY_TOKEN is not set, the value is an empty string
          echo "Token length: ${#DEPLOY_TOKEN}" # => Prints character count (not value)
          curl -H "Authorization: Bearer $DEPLOY_TOKEN" https://api.example.com/deploy
          # => curl sends the token in the Authorization header
          # => GitHub masks the token value in the log output

      - name: Pass secret to a script
        # => Secrets can also be passed inline using ${{ secrets.NAME }}
        # => but env: mapping is safer — it avoids shell injection risks
        run: ./scripts/publish.sh
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # => Available as $NPM_TOKEN inside the shell script

# => File: .github/workflows/env-scopes.yml
name: env-scopes

on: [push]

env:
  # => Workflow-level: visible to ALL jobs and ALL steps
  APP_ENV: staging # => $APP_ENV is "staging" everywhere unless overridden
  VERSION: "1.2.3" # => Accessible as $VERSION in every step

jobs:
  build:
    runs-on: ubuntu-latest

    env:
      # => Job-level: visible only to steps inside this job
      # => Inherits workflow-level vars; can add new ones or shadow existing ones
      DB_HOST: localhost # => $DB_HOST available in all steps of this job

    steps:
      - name: Show workflow-level var
        # => No local env: block; inherits APP_ENV=staging from workflow level
        run: echo "Env is $APP_ENV" # => Output: Env is staging

      - name: Show job-level var
        run: echo "DB host is $DB_HOST" # => Output: DB host is localhost

      - name: Step-level override
        env:
          # => Step-level env: shadows the workflow-level APP_ENV for this step only
          APP_ENV: production # => Overrides staging for this step only
        run: |
          echo "Env is $APP_ENV"  # => Output: Env is production (step override)
          echo "DB is $DB_HOST"   # => Output: DB is localhost (job-level still visible)
          echo "Ver is $VERSION"  # => Output: Ver is 1.2.3 (workflow-level still visible)

      - name: Back to workflow scope
        # => Step-level override from previous step does NOT persist
        run: echo "Env is $APP_ENV" # => Output: Env is staging (reverts to workflow-level)

# => File: .github/workflows/matrix-build.yml
name: matrix-build

on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    # => matrix.os is substituted per job instance
    # => GitHub creates one job per combination of (os × node-version)

    strategy:
      matrix:
        os: [ubuntu-22.04, windows-latest]
        # => Two OS values → jobs run on Ubuntu 22.04 and Windows
        node-version: [18, 20]
        # => Two Node versions → 2 × 2 = 4 total job instances

      fail-fast: false
      # => false: if one matrix job fails, others continue running
      # => true (default): any failure cancels all remaining matrix jobs
      # => false is usually preferable for cross-platform debugging

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          # => matrix.node-version is substituted: 18 or 20

      - run: npm ci # => Install exact locked dependencies
      - run: npm test # => Run tests on the current OS + Node combination

      - name: Report matrix values
        run: |
          echo "OS: ${{ matrix.os }}"                   # => e.g. ubuntu-22.04
          echo "Node: ${{ matrix.node-version }}"       # => e.g. 18
          echo "Runner OS: ${{ runner.os }}"            # => Linux or Windows

# => File: .github/workflows/matrix-include-exclude.yml
name: matrix-include-exclude

on: [push]

jobs:
  build:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.10", "3.11", "3.12"]
        # => Cartesian product: 3 × 3 = 9 combinations initially

        exclude:
          # => Remove specific combinations from the matrix
          - os: windows-latest
            python-version: "3.10"
            # => Drops: windows-latest + 3.10 → 8 combinations remain
          - os: macos-latest
            python-version: "3.10"
            # => Drops: macos-latest + 3.10 → 7 combinations remain

        include:
          # => Add a completely new combination not in the base matrix
          - os: ubuntu-latest
            python-version: "3.9"
            experimental: true
            # => This adds ubuntu + 3.9 AND sets matrix.experimental=true for it
          # => include can also inject extra keys into existing combinations
          - os: ubuntu-latest
            python-version: "3.12"
            coverage: true
            # => Adds matrix.coverage=true only for ubuntu + 3.12

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          # => Uses the python version for this matrix instance

      - name: Run tests
        run: pytest

      - name: Upload coverage
        if: ${{ matrix.coverage == true }}
        # => Only runs on the ubuntu + 3.12 combination where coverage=true
        run: pytest --cov=src --cov-report=xml

# => File: .github/workflows/cache-node.yml
name: cache-node

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Cache node_modules
        uses: actions/cache@v4
        id: node-cache
        # => id lets us reference this step's outputs later
        with:
          path: node_modules
          # => Directory to cache and restore; can be a list of paths
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          # => Cache key uniquely identifies the cached content
          # => runner.os: Linux/macOS/Windows (keeps caches OS-separate)
          # => hashFiles: computes SHA-256 of all package-lock.json files
          # => If package-lock.json changes, hash changes → cache miss → fresh install
          restore-keys: |
            ${{ runner.os }}-node-
            # => Fallback prefix: if exact key misses, restore nearest partial match
            # => Useful for getting a near-current cache when a dep was just updated

      - name: Install dependencies (if cache miss)
        if: steps.node-cache.outputs.cache-hit != 'true'
        # => cache-hit is 'true' only on exact key match
        # => Skip npm ci entirely on cache hit to save ~30-60 seconds
        run: npm ci

      - run: npm run build # => Compile with cached or freshly installed node_modules
      - run: npm test # => Run tests

# => File: .github/workflows/cache-go.yml
name: cache-go

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"
          cache: true
          # => setup-go@v5 has built-in caching when cache: true
          # => It automatically caches ~/go/pkg/mod (module download cache)
          # => and ~/.cache/go-build (compiled object cache)
          # => The cache key is derived from go.sum automatically

      - name: Run tests
        run: go test ./...
        # => Modules served from cache on subsequent runs
        # => Build cache avoids recompiling unchanged packages

      - name: Manual cache example (alternative approach)
        # => You can also control caching explicitly with actions/cache
        # => Shown here for illustration; normally setup-go cache: true is sufficient
        uses: actions/cache@v4
        with:
          path: |
            ~/go/pkg/mod
            ~/.cache/go-build
            # => Two directories: downloaded modules and compiled object files
          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
          # => go.sum is the Go equivalent of package-lock.json
          # => Contains cryptographic hashes of all module dependencies
          restore-keys: |
            ${{ runner.os }}-go-

# => File: .github/workflows/artifacts.yml
name: artifacts

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Build project
        run: |
          mkdir -p dist
          echo "compiled binary content" > dist/app   # => Simulate a build output
          echo "1.2.3" > dist/VERSION                 # => Write version file

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          # => Artifact name; used to reference in download-artifact
          # => Visible in the Actions UI under "Artifacts" after the run
          path: dist/
          # => Directory or glob to upload; preserves directory structure
          retention-days: 7
          # => Artifact expires after 7 days (default is 90; max is 400 days)
          if-no-files-found: error
          # => error: fail the step if path matches nothing
          # => warn: print warning but continue
          # => ignore: silently continue

  integration-test:
    runs-on: ubuntu-latest
    needs: build
    # => This job runs only after "build" succeeds

    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: build-output
          # => Must match the name used in upload-artifact
          path: dist/
          # => Restore artifact into dist/ directory on this runner

      - name: Run integration test
        run: |
          ls -la dist/              # => Output: app  VERSION
          cat dist/VERSION          # => Output: 1.2.3
          chmod +x dist/app
          ./dist/app || true        # => Execute the "binary"

# => File: .github/workflows/job-outputs.yml
name: job-outputs

on: [push]

jobs:
  compute-version:
    runs-on: ubuntu-latest

    outputs:
      # => Declare which step outputs to expose as job outputs
      version: ${{ steps.get-version.outputs.version }}
      # => Format: steps.<step-id>.outputs.<output-name>
      sha-short: ${{ steps.get-sha.outputs.sha }}

    steps:
      - uses: actions/checkout@v4

      - name: Get version from package.json
        id: get-version
        # => id is required to reference this step's outputs
        run: |
          VERSION=$(jq -r .version package.json)
          # => jq reads .version field from package.json
          # => VERSION variable is now e.g. "2.1.0"
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
          # => Write to the special $GITHUB_OUTPUT file
          # => Format: key=value (one per line)
          # => GitHub reads this file and populates steps.get-version.outputs.version

      - name: Get short SHA
        id: get-sha
        run: |
          SHA=$(git rev-parse --short HEAD)
          # => --short produces first 7 characters of commit SHA
          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
          # => steps.get-sha.outputs.sha is now e.g. "abc1234"

  build-image:
    runs-on: ubuntu-latest
    needs: compute-version
    # => Runs after compute-version completes; inherits its outputs

    steps:
      - name: Use version output
        run: |
          echo "Building version: ${{ needs.compute-version.outputs.version }}"
          # => Output: Building version: 2.1.0
          echo "Commit: ${{ needs.compute-version.outputs.sha-short }}"
          # => Output: Commit: abc1234
          # => These values come from the compute-version job's GITHUB_OUTPUT writes

# => File: .github/workflows/needs-conditional.yml
name: needs-conditional

on:
  push:
    branches: ["main"]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
      # => If npm test exits non-zero, the test job is marked "failure"
      # => This propagates to downstream jobs that depend on it

  deploy:
    runs-on: ubuntu-latest
    needs: test
    # => deploy runs only after test completes (any outcome)
    # => But the if: condition below further restricts execution

    if: ${{ success() }}
    # => success(): true when ALL jobs in needs list succeeded
    # => This is actually the default — explicit here for clarity
    # => If test failed, this job is skipped (not failed)

    steps:
      - uses: actions/checkout@v4
      - run: npm run deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

  notify-failure:
    runs-on: ubuntu-latest
    needs: test
    # => Also depends on test

    if: ${{ failure() }}
    # => failure(): true when ANY job in needs list failed
    # => This job runs ONLY when test fails

    steps:
      - name: Send Slack notification
        run: |
          curl -X POST -H "Content-type: application/json" \
            --data '{"text":"Tests failed on main!"}' \
            ${{ secrets.SLACK_WEBHOOK }}

  cleanup:
    runs-on: ubuntu-latest
    needs: [test, deploy]
    # => cleanup depends on both test AND deploy

    if: ${{ always() }}
    # => always(): runs regardless of upstream success or failure
    # => Use for cleanup tasks that must run even if pipeline failed

    steps:
      - run: echo "Cleaning up temporary resources"
        # => This step runs whether test passed, failed, or was cancelled

# => File: .github/workflows/concurrency.yml
name: concurrency

on:
  push:
    branches: ["main", "feature/**"]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  # => concurrency.group defines a named mutex
  # => github.workflow: workflow file name → "concurrency"
  # => github.ref: branch or PR ref → refs/heads/main or refs/pull/123/merge
  # => Combined key: "concurrency-refs/heads/main" — unique per workflow + branch
  # => Two runs targeting the same branch share this group and cannot run in parallel

  cancel-in-progress: true
  # => true: cancel any currently-running job in this group when a new run starts
  # => This is ideal for push-triggered workflows: only the latest commit matters
  # => false: queue the new run; the in-progress run completes first (safer for deploys)

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - run: npm test

# => File: .github/workflows/job-concurrency.yml
name: job-concurrency

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    # => No concurrency at job level; multiple test runs proceed in parallel
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  deploy-staging:
    runs-on: ubuntu-latest
    needs: test

    concurrency:
      group: deploy-staging
      # => All runs share the single group "deploy-staging"
      # => Regardless of branch or PR — only one staging deploy at a time
      cancel-in-progress: false
      # => Queue deploys; do not cancel an in-progress deploy
      # => Staging environment is single-instance — concurrent deploys would corrupt it

    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh staging

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging

    concurrency:
      group: deploy-production
      # => Separate group for production; serialized independently of staging
      cancel-in-progress: false
      # => Never cancel a production deploy — always let it finish

    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh production

# => File: .github/workflows/permissions.yml
name: permissions

on:
  push:
    branches: ["main"]
  release:
    types: [created]

permissions:
  # => Workflow-level default permissions for GITHUB_TOKEN
  # => These apply to all jobs unless overridden at the job level
  contents: read
  # => read: allows checkout; write: allows pushing commits and tags
  packages: write
  # => write: allows pushing to GitHub Container Registry (ghcr.io)
  # => read is default; write needed only for publishing packages

jobs:
  publish:
    runs-on: ubuntu-latest

    permissions:
      # => Job-level permissions OVERRIDE the workflow-level permissions
      # => Only this job can write packages; other jobs stay at workflow defaults
      contents: read
      packages: write
      # => Principle of least privilege: publish job only gets what it needs

    steps:
      - uses: actions/checkout@v4

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          # => github.actor: the user or app that triggered the workflow
          password: ${{ secrets.GITHUB_TOKEN }}
          # => GITHUB_TOKEN is auto-generated per run; no manual secret needed
          # => Its scope is limited to the permissions declared above

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          # => github.repository: owner/repo-name

  read-only-job:
    runs-on: ubuntu-latest
    # => Inherits workflow-level permissions: contents=read, packages=write
    # => For extra safety, override to read-only
    permissions:
      contents: read
      packages: read # => This job cannot push images

    steps:
      - uses: actions/checkout@v4
      - run: echo "This job can only read, not write"

# => File: .github/workflows/status-functions.yml
name: status-functions

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
        id: build-step
        # => If this command exits non-zero, the step (and job) is marked "failure"

  report-success:
    runs-on: ubuntu-latest
    needs: build
    if: ${{ success() }}
    # => success(): evaluates to true when ALL jobs in the needs list have status "success"
    # => Equivalent to: needs.build.result == 'success'
    # => This is the DEFAULT behavior for jobs with needs: — explicit here for clarity
    steps:
      - run: echo "Build succeeded — publishing artifacts"

  report-failure:
    runs-on: ubuntu-latest
    needs: build
    if: ${{ failure() }}
    # => failure(): evaluates to true when ANY job in needs list has status "failure"
    # => Does NOT include "cancelled" — see cancelled() below
    steps:
      - run: echo "Build failed — alerting on-call engineer"

  teardown:
    runs-on: ubuntu-latest
    needs: [build, report-success, report-failure]
    if: ${{ always() }}
    # => always(): evaluates to true regardless of any upstream status
    # => Runs even if a job was cancelled (unlike success() or failure())
    # => Use for guaranteed cleanup steps
    steps:
      - run: echo "Teardown runs in all scenarios"

  post-cancel:
    runs-on: ubuntu-latest
    needs: build
    if: ${{ cancelled() }}
    # => cancelled(): true when the workflow run was explicitly cancelled
    # => by a user clicking "Cancel" in the UI or via the API
    # => NOT triggered by job failures — only explicit user cancellation
    steps:
      - run: echo "Workflow was manually cancelled — releasing held locks"

  combined-condition:
    runs-on: ubuntu-latest
    needs: build
    if: ${{ failure() || cancelled() }}
    # => Boolean operators work in expressions
    # => This job runs on either failure OR explicit cancellation
    steps:
      - run: echo "Something went wrong or was cancelled"

# => File: .github/workflows/github-context.yml
name: github-context

on: [push, pull_request, workflow_dispatch]

jobs:
  inspect:
    runs-on: ubuntu-latest

    steps:
      - name: Print key github context values
        run: |
          echo "Workflow:    ${{ github.workflow }}"
          # => Name of the current workflow (from the name: key above)
          # => Output: github-context

          echo "Run ID:      ${{ github.run_id }}"
          # => Unique numeric ID for this workflow run
          # => Used in artifact names and external tracking systems

          echo "Event:       ${{ github.event_name }}"
          # => The trigger event: push, pull_request, workflow_dispatch, etc.

          echo "Ref:         ${{ github.ref }}"
          # => Full git ref: refs/heads/main or refs/pull/42/merge

          echo "SHA:         ${{ github.sha }}"
          # => Full 40-character commit SHA that triggered the workflow

          echo "Actor:       ${{ github.actor }}"
          # => GitHub username of the person or app that triggered the run

          echo "Repository:  ${{ github.repository }}"
          # => Format: owner/repo-name  e.g. acme/my-app

          echo "Workspace:   ${{ github.workspace }}"
          # => Absolute path to the checked-out code on the runner

      - name: Branch-specific logic
        if: ${{ github.ref == 'refs/heads/main' }}
        # => Only runs on pushes to main branch
        # => github.ref is the full ref string; use == for exact comparison
        run: echo "On main branch — deploying"

      - name: PR-specific logic
        if: ${{ github.event_name == 'pull_request' }}
        run: |
          echo "PR number:   ${{ github.event.pull_request.number }}"
          # => github.event contains the full webhook payload
          # => For pull_request events, github.event.pull_request has PR metadata
          echo "PR title:    ${{ github.event.pull_request.title }}"
          echo "Base branch: ${{ github.event.pull_request.base.ref }}"

# => File: .github/workflows/contexts.yml
name: contexts

on: [push]

env:
  APP_NAME: my-app # => Accessible as ${{ env.APP_NAME }} in all jobs/steps

jobs:
  inspect:
    runs-on: ubuntu-latest

    steps:
      - name: env context
        run: |
          echo "App name: ${{ env.APP_NAME }}"
          # => env context: reads workflow/job/step-level environment variables
          # => Output: App name: my-app
          # => Different from $APP_NAME shell syntax; use in expressions and conditionals

      - name: Produce a step output
        id: step-one
        run: |
          echo "result=42" >> "$GITHUB_OUTPUT"
          # => Write to GITHUB_OUTPUT to create a step output

      - name: steps context
        run: |
          echo "Previous step result: ${{ steps.step-one.outputs.result }}"
          # => steps context: access outputs from earlier steps in the same job
          # => Format: steps.<step-id>.outputs.<output-name>
          # => Output: Previous step result: 42

          echo "Previous step outcome: ${{ steps.step-one.outcome }}"
          # => steps.<id>.outcome: success | failure | cancelled | skipped
          # => Use to branch logic based on whether a prior step succeeded

      - name: runner context
        run: |
          echo "OS:   ${{ runner.os }}"
          # => runner.os: Linux | macOS | Windows
          echo "Arch: ${{ runner.arch }}"
          # => runner.arch: X64 | ARM | ARM64
          echo "Temp: ${{ runner.temp }}"
          # => runner.temp: path to a temp directory; cleaned up after each job

      - name: job context
        if: ${{ job.status == 'success' }}
        # => job.status: success | failure | cancelled
        # => Available in steps with if: conditions
        run: echo "Job is currently in success state"

# => File: .github/workflows/hashfiles.yml
name: hashfiles

on: [push]

jobs:
  cache-demo:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Show hash values
        run: |
          echo "package-lock hash: ${{ hashFiles('**/package-lock.json') }}"
          # => hashFiles('glob'): computes SHA-256 of all matching files
          # => Output: a hex string like "a1b2c3d4..."
          # => If package-lock.json changes between runs, hash changes

          echo "Multi-file hash: ${{ hashFiles('**/go.sum', '**/go.mod') }}"
          # => hashFiles accepts multiple globs; all matching files contribute to the hash
          # => Useful when both go.mod and go.sum must be unchanged for a valid cache

      - name: Cache with computed key
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          # => If package-lock.json is identical to a previous run, exact cache hit
          # => If package-lock.json changed, cache miss → fresh npm ci
          restore-keys: |
            ${{ runner.os }}-npm-
            # => Partial match fallback: restores most recent npm cache for this OS

      - name: Install and build
        run: |
          npm ci    # => Uses cached ~/.npm if cache hit
          npm build

# => File: .github/workflows/json-functions.yml
name: json-functions

on: [push]

jobs:
  json-demo:
    runs-on: ubuntu-latest

    steps:
      - name: toJSON example — inspect full context
        run: |
          echo '${{ toJSON(github) }}' | head -20
          # => toJSON(github): serializes the entire github context to JSON
          # => Useful for debugging — see every field the context provides
          # => Output: formatted JSON with event, sha, ref, actor, etc.

      - name: fromJSON example — parse a JSON string
        id: parse
        env:
          CONFIG: '{"environment":"staging","replicas":3,"debug":true}'
          # => A JSON string stored in an env var (could come from a secret or file)
        run: |
          echo "environment=${{ fromJSON(env.CONFIG).environment }}" >> "$GITHUB_OUTPUT"
          # => fromJSON parses env.CONFIG as JSON, then .environment reads the field
          # => Output: environment=staging
          echo "replicas=${{ fromJSON(env.CONFIG).replicas }}" >> "$GITHUB_OUTPUT"
          # => Output: replicas=3

      - name: Use parsed values
        run: |
          echo "Deploying to: ${{ steps.parse.outputs.environment }}"
          # => Output: Deploying to: staging
          echo "Replica count: ${{ steps.parse.outputs.replicas }}"
          # => Output: Replica count: 3

      - name: fromJSON for matrix (advanced pattern)
        # => fromJSON can generate a dynamic matrix from a JSON array string
        # => Example: if a previous step outputs '["app-a","app-b","app-c"]'
        # => then: matrix: service: ${{ fromJSON(steps.list.outputs.services) }}
        # => creates one job per element in the array
        run: echo "Dynamic matrix pattern shown above as comment for illustration"

# => File: .github/workflows/services.yml
name: services

on: [push, pull_request]

jobs:
  integration-test:
    runs-on: ubuntu-latest

    services:
      # => Each key under services: defines a named Docker container
      postgres:
        image: postgres:15
        # => Docker image to pull and start
        env:
          POSTGRES_USER: testuser
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb
          # => Environment variables passed to the container at start
        ports:
          - 5432:5432
          # => Map container port 5432 to host port 5432
          # => Steps connect via localhost:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
          # => Health check: job steps don't start until pg_isready returns 0
          # => Without health checks, steps may start before the DB is ready

      redis:
        image: redis:7
        ports:
          - 6379:6379
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 3s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - name: Run integration tests
        env:
          DATABASE_URL: postgresql://testuser:testpass@localhost:5432/testdb
          # => Connect to the postgres service on localhost
          # => Port mapping makes the container reachable at localhost:5432
          REDIS_URL: redis://localhost:6379
        run: |
          npm ci
          npm run test:integration
          # => Tests connect to real Postgres and Redis instances
          # => No mocking required; tests exercise actual SQL and cache behavior

# => File: .github/workflows/container-job.yml
name: container-job

on: [push]

jobs:
  test-in-container:
    runs-on: ubuntu-latest
    # => ubuntu-latest is still required as the host OS for Docker

    container:
      image: node:20-alpine
      # => ALL steps in this job run inside this container
      # => The container inherits the checked-out source from the runner
      env:
        NODE_ENV: test
        # => Environment variable set inside the container
      credentials:
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
        # => Credentials for authenticated private registry pulls
        # => Not needed for public Docker Hub images

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        options: --health-cmd pg_isready --health-interval 10s --health-retries 5
        # => Services work the same way in container jobs
        # => The job container connects to postgres via the service name "postgres"
        # => NOT localhost — service name is the hostname in container jobs

    steps:
      - uses: actions/checkout@v4
        # => Source code is mounted into the container at github.workspace

      - name: Check Node version inside container
        run: node --version
        # => Output: v20.x.x — proves we're running inside the node:20-alpine image

      - name: Install and test
        env:
          DATABASE_URL: postgres://test:test@postgres:5432/testdb
          # => In container jobs: use service NAME "postgres" as hostname
          # => NOT localhost — that's only for non-container jobs
        run: |
          npm ci
          npm test

# => File: .github/actions/setup-env/action.yml
# => This file defines a LOCAL composite action stored at .github/actions/setup-env/
name: Setup Environment
description: Install dependencies and configure environment

inputs:
  node-version:
    description: Node.js version to install
    required: false
    default: "20"
    # => Callers can override the default; omitting node-version uses "20"

outputs:
  cache-hit:
    description: Whether the node_modules cache was hit
    value: ${{ steps.cache.outputs.cache-hit }}
    # => Expose the inner step's output to the action caller

runs:
  using: composite
  # => composite: steps run in the caller's runner environment
  # => (vs javascript or docker action types)

  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        # => inputs.node-version reads the caller's value or the default

    - id: cache
      uses: actions/cache@v4
      with:
        path: node_modules
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

    - name: Install dependencies
      if: steps.cache.outputs.cache-hit != 'true'
      run: npm ci
      shell: bash
      # => shell: is REQUIRED in composite action steps
      # => Must explicitly specify bash, sh, pwsh, etc.

# => File: .github/workflows/use-local-action.yml
# => This workflow USES the composite action defined above
name: use-local-action

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup environment using local action
        id: setup
        uses: ./.github/actions/setup-env
        # => ./ prefix means "local to this repository"
        # => Path is relative to the repository root
        with:
          node-version: "18"
          # => Override the default node-version input

      - name: Check cache hit output
        run: |
          echo "Cache hit: ${{ steps.setup.outputs.cache-hit }}"
          # => Output: Cache hit: true (if cache existed) or false (first run)

      - run: npm run build
      - run: npm test

# => File: .github/workflows/reusable-build.yml
# => This is the REUSABLE workflow — called by other workflows
name: reusable-build

on:
  workflow_call:
    # => workflow_call: makes this workflow invokable from other workflows
    # => Without this trigger, no external workflow can call it

    inputs:
      environment:
        description: Target environment (staging or production)
        required: true
        type: string
        # => type is required for workflow_call inputs: string | boolean | number
      version:
        required: false
        type: string
        default: "latest"

    secrets:
      REGISTRY_TOKEN:
        required: true
        # => Secrets must be explicitly declared; they are not inherited automatically

    outputs:
      image-tag:
        description: The published Docker image tag
        value: ${{ jobs.build.outputs.tag }}
        # => Expose a job output from this workflow to the caller

jobs:
  build:
    runs-on: ubuntu-latest

    outputs:
      tag: ${{ steps.tag.outputs.value }}

    steps:
      - uses: actions/checkout@v4

      - id: tag
        run: |
          TAG="${{ inputs.environment }}-${{ inputs.version }}"
          echo "value=$TAG" >> "$GITHUB_OUTPUT"
          # => Constructs tag like "staging-1.2.0" or "production-latest"

      - name: Build and push image
        run: |
          echo "Building for ${{ inputs.environment }} with tag ${{ steps.tag.outputs.value }}"
          # => Would push to registry using ${{ secrets.REGISTRY_TOKEN }}

# => File: .github/workflows/deploy.yml
# => This is the CALLER workflow
name: deploy

on:
  push:
    branches: ["main"]

jobs:
  run-reusable-build:
    uses: ./.github/workflows/reusable-build.yml
    # => uses: path to the reusable workflow
    # => ./ means same repository; can also use owner/repo/.github/workflows/file.yml@ref
    with:
      environment: staging
      version: ${{ github.sha }}
      # => Pass the commit SHA as the version
    secrets:
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
      # => Secrets must be explicitly forwarded; they are not inherited

  use-output:
    runs-on: ubuntu-latest
    needs: run-reusable-build
    steps:
      - run: |
          echo "Image tag: ${{ needs.run-reusable-build.outputs.image-tag }}"
          # => Reads the output that the reusable workflow exposed
          # => Output: Image tag: staging-abc1234

# => File: .github/workflows/event-context.yml
name: event-context

on:
  push:
  pull_request:
    types: [opened, synchronize, labeled]
    # => types filter which PR actions trigger the workflow

jobs:
  inspect-event:
    runs-on: ubuntu-latest

    steps:
      - name: Dump full event payload
        run: |
          echo '${{ toJSON(github.event) }}'
          # => toJSON(github.event): shows the complete webhook payload
          # => Use this during development to discover available fields

      - name: Push-specific fields
        if: ${{ github.event_name == 'push' }}
        run: |
          echo "Pusher:   ${{ github.event.pusher.name }}"
          # => pusher.name: GitHub username who pushed the commits

          echo "Commits:  ${{ toJSON(github.event.commits) }}"
          # => commits: array of pushed commit objects with sha, message, author

          echo "Before:   ${{ github.event.before }}"
          # => before: SHA of the commit before the push (parent)
          echo "After:    ${{ github.event.after }}"
          # => after: SHA of the HEAD commit after the push (same as github.sha)

      - name: PR-specific fields
        if: ${{ github.event_name == 'pull_request' }}
        run: |
          echo "PR number: ${{ github.event.pull_request.number }}"
          echo "PR action: ${{ github.event.action }}"
          # => action: opened | synchronize | labeled | closed etc.

          echo "Head SHA:  ${{ github.event.pull_request.head.sha }}"
          # => head.sha: the latest commit SHA on the PR branch

          echo "Labels: ${{ toJSON(github.event.pull_request.labels) }}"
          # => labels: array of label objects with name, color, description

      - name: Check for specific label
        if: >-
          github.event_name == 'pull_request' &&
          contains(github.event.pull_request.labels.*.name, 'deploy-preview')
        # => contains() checks if array includes a value
        # => *.name flattens the labels array to just name strings
        run: echo "PR has deploy-preview label — creating preview environment"

# => File: .github/workflows/repository-dispatch.yml
name: repository-dispatch

on:
  repository_dispatch:
    types: [deploy-requested, rollback-requested]
    # => types: filter which client_payload.event_type values trigger this workflow
    # => If types is omitted, all repository_dispatch events trigger it

jobs:
  handle-deploy:
    runs-on: ubuntu-latest
    if: ${{ github.event.action == 'deploy-requested' }}
    # => github.event.action: the event type sent by the API caller

    steps:
      - uses: actions/checkout@v4

      - name: Read dispatch payload
        run: |
          echo "Action:      ${{ github.event.action }}"
          # => Output: deploy-requested

          echo "Environment: ${{ github.event.client_payload.environment }}"
          # => client_payload: arbitrary JSON sent by the API caller
          # => Access any field with .client_payload.<field>

          echo "Version:     ${{ github.event.client_payload.version }}"
          echo "Requester:   ${{ github.event.client_payload.requester }}"

      - name: Deploy
        run: |
          ENV="${{ github.event.client_payload.environment }}"
          VER="${{ github.event.client_payload.version }}"
          echo "Deploying version $VER to $ENV"
          ./scripts/deploy.sh "$ENV" "$VER"

  handle-rollback:
    runs-on: ubuntu-latest
    if: ${{ github.event.action == 'rollback-requested' }}

    steps:
      - uses: actions/checkout@v4
      - name: Rollback
        run: |
          echo "Rolling back to ${{ github.event.client_payload.previous_version }}"
          ./scripts/rollback.sh "${{ github.event.client_payload.previous_version }}"

# => File: .github/workflows/environment-protection.yml
name: environment-protection

on:
  push:
    branches: ["main"]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    # => environment: maps this job to the "staging" GitHub Environment
    # => Staging might have no protection rules — deploys proceed immediately
    # => The environment's secrets are accessible in this job's steps

    steps:
      - uses: actions/checkout@v4
      - name: Deploy to staging
        run: ./scripts/deploy.sh staging
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          # => Environment-level secrets override repository secrets with the same name
          # => Staging's DEPLOY_KEY is different from production's DEPLOY_KEY

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment:
      name: production
      # => environment.name: the environment name (as defined in Settings → Environments)
      url: https://app.example.com
      # => environment.url: shown in the deployment panel and PR status checks
      # => Links reviewers directly to the deployed application

    # => If "production" has required reviewers:
    # => The job pauses here until an approver clicks "Approve" in the UI
    # => If "production" has a wait timer:
    # => The job waits that many minutes after approval before running
    # => If "production" restricts deployment branches:
    # => Only allowed branches (e.g., main) can deploy here

    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        run: ./scripts/deploy.sh production
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          # => This is production's DEPLOY_KEY — a different value than staging's

# => File: .github/workflows/expressions.yml
name: expressions

on: [push, pull_request, workflow_dispatch]

jobs:
  expression-demo:
    runs-on: ubuntu-latest

    steps:
      - name: Comparison operators
        run: |
          echo "Ref is main: ${{ github.ref == 'refs/heads/main' }}"
          # => == equality comparison; returns true or false
          echo "Not main:    ${{ github.ref != 'refs/heads/main' }}"
          # => != inequality
          echo "Run number:  ${{ github.run_number > 1 }}"
          # => > numeric greater-than; run_number increments per run

      - name: Logical operators
        if: >-
          github.event_name == 'push' &&
          github.ref == 'refs/heads/main'
        # => && logical AND; both conditions must be true
        # => >- is YAML multi-line scalar: joins lines without newlines
        run: echo "This only runs on push to main"

      - name: contains() function
        if: ${{ contains(github.ref, 'feature/') }}
        # => contains(haystack, needle): true if haystack includes needle
        # => Works on strings and arrays
        run: echo "This is a feature branch"

      - name: startsWith() and endsWith()
        run: |
          echo "${{ startsWith(github.ref, 'refs/tags/') }}"
          # => startsWith(string, prefix): true if string begins with prefix
          # => Use for tag-triggered logic: refs/tags/v1.2.3

          echo "${{ endsWith(github.ref, '-rc') }}"
          # => endsWith(string, suffix): true if string ends with suffix
          # => Use for release candidate branches

      - name: format() function
        run: |
          echo "${{ format('Hello {0}, your run is {1}', github.actor, github.run_number) }}"
          # => format(template, ...args): substitutes {0}, {1} etc. with args
          # => Output: Hello octocat, your run is 42

      - name: join() function
        run: |
          echo "${{ join(github.event.commits.*.message, ', ') }}"
          # => join(array, separator): joins array elements with separator
          # => Useful for combining commit messages into a single string

      - name: Ternary-like pattern
        run: |
          echo "${{ github.event_name == 'push' && 'was a push' || 'was not a push' }}"
          # => && and || provide ternary-like behavior in expressions
          # => condition && trueValue || falseValue
          # => Note: falseValue is returned if trueValue is falsy (empty string, 0, false)

# => File: .github/workflows/full-pipeline.yml
name: full-pipeline

on:
  push:
    branches: ["main"]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
  # => Cancel in-progress only for PRs (stale PR builds waste time)
  # => On main branch pushes, cancel-in-progress is false — let deploys complete

permissions:
  contents: read
  packages: write
  # => Workflow-level: read source, write packages (Docker images)

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
  # => Shared across all jobs; no repetition

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20]
        # => Run tests on both Node versions in parallel
      fail-fast: false

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm
          # => setup-node handles npm caching automatically

      - run: npm ci
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@v4
        with:
          name: coverage-node-${{ matrix.node }}
          path: coverage/
          retention-days: 3
          # => Upload coverage per matrix cell with unique names

  build:
    runs-on: ubuntu-latest
    needs: test
    # => Only build after all test matrix jobs pass

    outputs:
      image-tag: ${{ steps.meta.outputs.tags }}

    steps:
      - uses: actions/checkout@v4

      - id: meta
        run: |
          TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}"
          echo "tags=$TAG" >> "$GITHUB_OUTPUT"
          # => Compute image tag from registry, repo, and commit SHA

      - name: Build Docker image
        run: |
          docker build -t "${{ steps.meta.outputs.tags }}" .
          docker push "${{ steps.meta.outputs.tags }}"
          # => In production: use docker/login-action and build-push-action

  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: ${{ github.ref == 'refs/heads/main' }}
    # => Only deploy from main branch; PRs stop at build
    environment:
      name: production
      url: https://app.example.com
    steps:
      - run: |
          echo "Deploying image: ${{ needs.build.outputs.image-tag }}"
          # => Uses the image tag output from the build job
          ./scripts/deploy.sh "${{ needs.build.outputs.image-tag }}"
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}