Workflow YAML Anatomy

permissions:
  contents: read      # Can read repo contents (checkout)
  packages: write     # Can push to GitHub Container Registry
  pull-requests: none # No PR access needed

# Workflow-level — available in ALL jobs and steps
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    # Job-level — available in all steps of THIS job only
    env:
      NODE_ENV: production
    steps:
      - name: Deploy
        # Step-level — available only in THIS step
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: echo "Deploying with $DEPLOY_TOKEN"

defaults:
  run:
    shell: bash
    working-directory: ./src

# ─── WORKFLOW NAME ───────────────────────────────────────────
# name: Human-readable label that appears in the Actions tab.
#   This is what you and your team see when browsing workflow runs.
name: Build and Deploy

# ─── TRIGGERS ────────────────────────────────────────────────
# on: Defines WHEN this workflow runs. Without this, nothing triggers.
on:

  # push: Triggers when commits are pushed to a matching branch.
  push:
    # branches: Only trigger on pushes to 'main' or 'develop'.
    #   Pushes to feature branches are ignored — they use pull_request instead.
    branches: [main, develop]
    # paths: Only trigger when files in these directories change.
    #   If you only change README.md, this workflow won't run — saving minutes.
    paths:
      - 'src/**'
      - 'Dockerfile'

  # pull_request: Triggers when a PR targeting a matching branch is opened or updated.
  pull_request:
    # types: Only trigger on these specific PR activities.
    #   'opened' — PR is created.  'synchronize' — new commits pushed to PR branch.
    #   Without this filter, events like 'labeled' or 'closed' would also trigger the workflow.
    types: [opened, synchronize]

  # workflow_dispatch: Adds a "Run workflow" button in the Actions UI.
  #   Allows manual triggering with custom inputs — perfect for controlled deployments.
  workflow_dispatch:
    inputs:
      environment:
        # description: Help text shown next to the input field in the UI.
        description: 'Target environment'
        # required: User must provide this value before the workflow can start.
        required: true
        # default: Pre-selected value when the dropdown loads.
        default: 'staging'
        # type: Input type — 'choice' renders a dropdown, 'string' renders a text field.
        type: choice
        # options: The allowed values for the dropdown.
        options: [staging, production]

# ─── PERMISSIONS ─────────────────────────────────────────────
# permissions: Restricts what the GITHUB_TOKEN can do.
#   This follows the principle of least privilege — only grant what's needed.
#   Without this block, the token gets broad default permissions.
permissions:
  contents: read     # Can clone the repo (needed by actions/checkout)
  packages: write    # Can push Docker images to GitHub Container Registry (ghcr.io)

# ─── WORKFLOW-LEVEL ENVIRONMENT VARIABLES ────────────────────
# env: Variables available to EVERY job and step in this workflow.
#   Use this for values shared across multiple jobs — like registry URLs.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
  #   ${{ github.repository }} resolves to 'owner/repo' (e.g., 'octocat/my-app').
  #   The ${{ }} syntax is a GitHub Actions expression — evaluated at runtime.

# ─── JOBS ────────────────────────────────────────────────────
# jobs: The meat of the workflow. Each key below is a separate job.
#   Jobs run in parallel by default unless 'needs:' creates dependencies.
jobs:

  # ─── JOB 1: LINT ──────────────────────────────────────────
  # 'lint' is the job ID — unique within this workflow.
  #   Used by other jobs to reference it (e.g., needs: lint).
  lint:
    # runs-on: The runner (VM) that executes this job.
    #   'ubuntu-latest' = a fresh Ubuntu VM managed by GitHub.
    runs-on: ubuntu-latest

    # steps: Ordered list of tasks. Runs top-to-bottom, stops on first failure.
    steps:
      # Step 1: Clone the repository onto the runner.
      #   uses: references a pre-built action. actions/checkout@v4 clones your repo.
      #   Without this, the runner has an empty filesystem — no source code.
      - uses: actions/checkout@v4

      # Step 2: Run the linter.
      #   run: executes a shell command directly. 'npm run lint' runs your linting script.
      - run: npm run lint

  # ─── JOB 2: TEST ──────────────────────────────────────────
  test:
    runs-on: ubuntu-latest

    # needs: This job waits for 'lint' to succeed before starting.
    #   If lint fails, test is skipped. This creates a sequential dependency:
    #   lint → test (instead of both running in parallel).
    needs: lint

    # strategy.matrix: Run this SAME job multiple times with different configurations.
    #   Here we test against Node.js 18, 20, and 22 — three parallel job instances.
    strategy:
      matrix:
        node-version: [18, 20, 22]

    steps:
      - uses: actions/checkout@v4

      # Setup Node.js with the version from the current matrix combination.
      #   ${{ matrix.node-version }} resolves to 18, 20, or 22 depending on the instance.
      - uses: actions/setup-node@v4
        # with: Passes input parameters to the action.
        #   'node-version' is an input defined by actions/setup-node.
        with:
          node-version: ${{ matrix.node-version }}

      # Install dependencies using the lockfile (npm ci is stricter than npm install).
      - run: npm ci

      # Run the test suite. If any test fails, this step fails → job fails → workflow fails.
      - run: npm test

  # ─── JOB 3: BUILD ─────────────────────────────────────────
  build:
    runs-on: ubuntu-latest

    # needs: Waits for the 'test' job (all matrix instances) to pass.
    needs: test

    # if: Conditional — this job ONLY runs when the push is to the 'main' branch.
    #   On pull_request events or pushes to 'develop', this entire job is skipped.
    #   github.ref contains the full ref: 'refs/heads/main', 'refs/heads/develop', etc.
    if: github.ref == 'refs/heads/main'

    steps:
      - uses: actions/checkout@v4

      # Log in to GitHub Container Registry using the GITHUB_TOKEN.
      #   docker/login-action@v3 handles the docker login command for you.
      - uses: docker/login-action@v3
        with:
          # registry: Which registry to authenticate with.
          registry: ${{ env.REGISTRY }}
          # username: The GitHub user who triggered the workflow.
          username: ${{ github.actor }}
          # password: The auto-generated GITHUB_TOKEN — no need to create a secret.
          #   secrets.GITHUB_TOKEN is provided automatically by GitHub.
          password: ${{ secrets.GITHUB_TOKEN }}

      # Build the Docker image and push it to the registry in a single step.
      #   docker/build-push-action@v5 handles docker build + docker push.
      - uses: docker/build-push-action@v5
        with:
          # push: true means the image is pushed to the registry after building.
          push: true
          # tags: The full image name + tag. Uses the commit SHA for traceability.
          #   Result: ghcr.io/octocat/my-app:abc123def456
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t myacr.azurecr.io/webapp:latest .
      - run: docker push myacr.azurecr.io/webapp:latest
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - run: helm upgrade --install webapp ./charts/webapp --set image.repository=myacr.azurecr.io/webapp --set image.tag=latest

env:
  REGISTRY: ${{ vars.ACR_NAME }}.azurecr.io
  IMAGE: webapp
  TAG: ${{ github.sha }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ env.TAG }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - run: |
          helm upgrade --install ${{ env.IMAGE }} ./charts/${{ env.IMAGE }} \
            --set image.repository=${{ env.REGISTRY }}/${{ env.IMAGE }} \
            --set image.tag=${{ env.TAG }} \
            --atomic --wait --timeout 5m

jobs:
  everything:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: docker build -t myapp .
      - run: docker push myapp
      - run: helm upgrade --install myapp ./charts

jobs:
  lint:                        # Fast feedback — fails in seconds
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint

  test:
    needs: lint                # Only run if lint passes
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --coverage

  build-and-push:
    needs: test
    if: github.ref == 'refs/heads/main'  # Only build on main
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

  deploy:
    needs: build-and-push
    runs-on: ubuntu-latest
    environment: production    # Manual approval gate
    steps:
      - uses: actions/checkout@v4
      - run: helm upgrade --install myapp ./charts --atomic --wait

name: Deploy
on: push
# No permissions block — GITHUB_TOKEN gets full read/write access
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh

name: Deploy
on:
  push:
    branches: [main]

permissions:
  contents: read       # Only checkout — can't push code or delete branches
  id-token: write      # OIDC token for Azure login
  packages: write      # Push Docker images to GHCR

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - run: ./deploy.sh

# 10 different repos, each with identical 80-line workflow
# Bug fix = editing 10 files across 10 repos

# .github/workflows/ci.yml in each repo — 8 lines
name: CI
on: [push, pull_request]
jobs:
  ci:
    uses: my-org/.github/.github/workflows/standard-ci.yml@v2
    with:
      node-version: '20'
    secrets: inherit

      - run: |
          curl -fsSL https://get.docker.com | sh
          echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u user --password-stdin
          docker build -t myapp:${{ github.sha }} .
          docker push myapp:${{ github.sha }}

      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

name: Manual Greeting

on:
  workflow_dispatch:
    inputs:
      greeting:
        description: 'What greeting to display'
        required: true
        default: 'Hello from SKILLY!'
        type: string
      environment:
        description: 'Target environment'
        required: true
        default: 'dev'
        type: choice
        options: [dev, staging, production]

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Display the greeting
        run: |
          echo "Greeting: ${{ github.event.inputs.greeting }}"
          echo "Environment: ${{ github.event.inputs.environment }}"
          echo "Triggered by: ${{ github.actor }}"
          echo "Run ID: ${{ github.run_id }}"

name: Smart CI

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'package.json'
      - 'package-lock.json'
    # paths-ignore could also be used:
    # paths-ignore: ['docs/**', '*.md', '.gitignore']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Show changed files
        run: |
          echo "This workflow only runs when src/ or package files change."
          echo "Changes to README.md, docs/, or config files are ignored."
          git diff --name-only HEAD~1 || echo "First commit"

name: Matrix Test

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20]
      # fail-fast: false  # Uncomment to run all matrix combinations even if one fails
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Show Node version
        run: |
          echo "Testing with Node.js $(node --version)"
          echo "Matrix value: ${{ matrix.node-version }}"

name: Conditional Deploy

on:
  push:
    branches: [main, develop]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: echo "Building the application..."

      - name: Run tests
        run: echo "All tests passed ✅"

      # This step ONLY runs on the main branch.
      # On 'develop', it's skipped — you'll see a grey "skipped" icon.
      - name: Deploy to production
        if: github.ref == 'refs/heads/main'
        run: |
          echo "🚀 Deploying to production!"
          echo "Branch: ${{ github.ref }}"
          echo "SHA: ${{ github.sha }}"

      # This step runs on every branch EXCEPT main.
      - name: Deploy to staging
        if: github.ref != 'refs/heads/main'
        run: |
          echo "📦 Deploying to staging environment"
          echo "Branch: ${{ github.ref }}"

# .github/workflows/ci-frontend.yml
name: Frontend CI
on:
  push:
    paths: ['frontend/**', 'shared/**']
  pull_request:
    paths: ['frontend/**', 'shared/**']

# .github/workflows/ci-backend.yml
name: Backend CI
on:
  push:
    paths: ['backend/**', 'shared/**']
  pull_request:
    paths: ['backend/**', 'shared/**']

# .github/workflows/ci-shared.yml
name: Shared Library CI
on:
  push:
    paths: ['shared/**']
  pull_request:
    paths: ['shared/**']