Part 2: YAML Syntax and Workflow Fundamentals

Introduction

When I first started writing GitHub Actions workflows, I made a costly mistake: I indented with tabs instead of spaces in my YAML file. The workflow failed with a cryptic error message, and it took me an hour to figure out why. YAML is notoriously picky about formatting, but once you understand its rules, it becomes a powerful way to define your automation.

In this part, I'll teach you everything about YAML syntax for GitHub Actions, based on the mistakes I've made and the patterns I've refined in production workflows.

YAML Basics for GitHub Actions

What is YAML?

YAML (YAML Ain't Markup Language) is a human-readable data serialization format. GitHub Actions uses YAML to define workflows.

Key Rules:

• Use spaces for indentation (never tabs!)

• Indentation matters (like Python)

• Use 2 spaces per indentation level

• Case-sensitive

• Comments start with #

Basic YAML Syntax

# This is a comment

# String (no quotes needed)
name: CI Pipeline

# String with quotes (needed for special characters)
message: "Hello, World!"

# Number
timeout: 30

# Boolean
enabled: true
disabled: false

# List (array)
branches:
  - main
  - develop
  - staging

# Alternative list syntax
branches: [main, develop, staging]

# Object (dictionary/map)
environment:
  name: production
  url: https://api.example.com

# Nested structures
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

Complete Workflow Structure

Here's the complete structure of a GitHub Actions workflow file:

# Workflow name (appears in GitHub UI)
name: CI/CD Pipeline

# When to run this workflow
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

# Environment variables available to all jobs
env:
  NODE_VERSION: '18'
  DATABASE_URL: ${{ secrets.DATABASE_URL }}

# Default settings for all jobs
defaults:
  run:
    shell: bash
    working-directory: ./src

# Jobs to run
jobs:
  # Job ID
  test:
    # Job name (displayed in UI)
    name: Run Tests
    
    # Runner to use
    runs-on: ubuntu-latest
    
    # Job-specific environment variables
    env:
      NODE_ENV: test
    
    # Services (containers) for this job
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
    
    # Steps in this job
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ env.NODE_VERSION }}
      
      - name: Run tests
        run: npm test

Workflow Triggers (on)

Push Events

# Trigger on any push
on: push

# Trigger on push to specific branches
on:
  push:
    branches:
      - main
      - develop
      - 'release/**'  # Pattern matching

# Trigger on push to specific paths
on:
  push:
    paths:
      - 'src/**'
      - 'package.json'
      - '.github/workflows/**'

# Exclude certain paths
on:
  push:
    paths-ignore:
      - 'docs/**'
      - '**.md'

Real example from my API service:

# Only run when API code changes
on:
  push:
    branches: [main, develop]
    paths:
      - 'services/api/**'
      - 'packages/shared-types/**'
      - '.github/workflows/api-ci.yml'

Pull Request Events

on:
  pull_request:
    types:
      - opened        # PR created
      - synchronize   # New commits pushed
      - reopened      # PR reopened
      - ready_for_review  # Draft → Ready
    branches:
      - main
      - develop

Release Events

on:
  release:
    types:
      - published  # Release published
      - created    # Release created (draft or published)

My production deployment workflow:

name: Deploy to Production

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: npm run deploy:production

Scheduled Events (Cron)

on:
  schedule:
    # Minute Hour Day Month DayOfWeek
    - cron: '0 2 * * *'  # Every day at 2 AM UTC
    - cron: '0 */6 * * *'  # Every 6 hours
    - cron: '0 0 * * 1'  # Every Monday at midnight

My dependency update check:

name: Check Dependencies

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM UTC

jobs:
  check-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm outdated

Manual Workflow Dispatch

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version to deploy'
        required: false
        type: string
        default: 'latest'
      dry_run:
        description: 'Perform dry run?'
        required: false
        type: boolean
        default: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: |
          echo "Deploying ${{ inputs.version }} to ${{ inputs.environment }}"
          echo "Dry run: ${{ inputs.dry_run }}"

Multiple Triggers

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'
  workflow_dispatch:

Jobs Configuration

Basic Job

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

Job Dependencies

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test
  
  build:
    runs-on: ubuntu-latest
    needs: test  # Waits for 'test' to complete
    steps:
      - run: npm run build
  
  deploy:
    runs-on: ubuntu-latest
    needs: [test, build]  # Waits for both
    steps:
      - run: npm run deploy

My production workflow:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - run: npm run lint
  
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test
  
  build:
    runs-on: ubuntu-latest
    needs: [lint, test]  # Only build if lint and test pass
    steps:
      - run: npm run build
  
  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'
    steps:
      - run: npm run deploy

Conditional Jobs

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/develop'
    steps:
      - run: npm run deploy:staging
  
  deploy-production:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - run: npm run deploy:production

Job Outputs

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.get_version.outputs.version }}
    steps:
      - id: get_version
        run: echo "version=$(cat package.json | jq -r .version)" >> $GITHUB_OUTPUT
  
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy version
        run: echo "Deploying version ${{ needs.build.outputs.version }}"

Steps Configuration

Using Actions

steps:
  # Use action with default settings
  - uses: actions/checkout@v3
  
  # Use action with parameters
  - uses: actions/setup-node@v3
    with:
      node-version: '18'
      cache: 'npm'
  
  # Use action with specific version
  - uses: actions/[email protected]
  
  # Use action from another repository
  - uses: docker/build-push-action@v4
    with:
      context: .
      push: true
      tags: user/app:latest

Running Commands

steps:
  # Single-line command
  - name: Install dependencies
    run: npm ci
  
  # Multi-line command
  - name: Run tests
    run: |
      npm run lint
      npm run type-check
      npm test
  
  # Command with custom shell
  - name: Run Python script
    run: python script.py
    shell: python
  
  # Command with working directory
  - name: Build frontend
    run: npm run build
    working-directory: ./frontend

Environment Variables in Steps

steps:
  # Step-level environment variables
  - name: Run tests
    run: npm test
    env:
      NODE_ENV: test
      API_KEY: ${{ secrets.API_KEY }}

Conditional Steps

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main'
    run: npm run deploy:production
  
  - name: Deploy to staging
    if: github.ref == 'refs/heads/develop'
    run: npm run deploy:staging
  
  # Run only on pull requests
  - name: Comment on PR
    if: github.event_name == 'pull_request'
    run: echo "This is a PR!"
  
  # Run only on success
  - name: Notify success
    if: success()
    run: echo "Workflow succeeded!"
  
  # Run only on failure
  - name: Notify failure
    if: failure()
    run: echo "Workflow failed!"
  
  # Always run (even if previous steps failed)
  - name: Cleanup
    if: always()
    run: echo "Cleaning up..."

Environment Variables and Secrets

Workflow-Level Environment Variables

env:
  NODE_VERSION: '18'
  DATABASE_NAME: myapp_db

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Node version: $NODE_VERSION"

Job-Level Environment Variables

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      NODE_ENV: test
      LOG_LEVEL: debug
    steps:
      - run: npm test

Using Secrets

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: npm run deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

Setting secrets in GitHub:

1. Go to repository Settings

2. Click Secrets and variables → Actions

3. Click "New repository secret"

4. Add name and value

Default Environment Variables

GitHub provides built-in environment variables:

steps:
  - name: Show GitHub context
    run: |
      echo "Repository: ${{ github.repository }}"
      echo "Branch: ${{ github.ref }}"
      echo "Commit SHA: ${{ github.sha }}"
      echo "Actor: ${{ github.actor }}"
      echo "Event: ${{ github.event_name }}"

Complete list of useful variables:

steps:
  - name: Use GitHub variables
    run: |
      echo "Workflow: ${{ github.workflow }}"
      echo "Action: ${{ github.action }}"
      echo "Run ID: ${{ github.run_id }}"
      echo "Run Number: ${{ github.run_number }}"
      echo "Job: ${{ github.job }}"
      echo "Repository: ${{ github.repository }}"
      echo "Repository Owner: ${{ github.repository_owner }}"
      echo "Ref: ${{ github.ref }}"
      echo "Ref Name: ${{ github.ref_name }}"
      echo "SHA: ${{ github.sha }}"
      echo "Actor: ${{ github.actor }}"
      echo "Event Name: ${{ github.event_name }}"
      echo "Workspace: ${{ github.workspace }}"
      echo "Server URL: ${{ github.server_url }}"

Context and Expressions

Using Contexts

steps:
  # GitHub context
  - name: Print branch
    run: echo "Branch: ${{ github.ref }}"
  
  # Env context
  - name: Print environment
    run: echo "Environment: ${{ env.NODE_ENV }}"
  
  # Secrets context
  - name: Use secret
    run: echo "API Key: ${{ secrets.API_KEY }}"
  
  # Steps context (from previous steps)
  - id: build
    run: echo "build_id=12345" >> $GITHUB_OUTPUT
  
  - name: Use output
    run: echo "Build ID: ${{ steps.build.outputs.build_id }}"
  
  # Jobs context (from other jobs)
  - name: Use job output
    run: echo "Version: ${{ needs.build.outputs.version }}"
  
  # Matrix context
  - name: Use matrix value
    run: echo "Node version: ${{ matrix.node }}"

Expressions and Functions

steps:
  # String functions
  - name: Lowercase
    run: echo "${{ lower('HELLO') }}"  # hello
  
  # Comparison
  - name: Check branch
    if: ${{ github.ref == 'refs/heads/main' }}
    run: echo "Main branch"
  
  # Logical operators
  - name: Run on main or develop
    if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop' }}
    run: echo "Main or develop"
  
  # Contains
  - name: Check if PR
    if: ${{ contains(github.event_name, 'pull_request') }}
    run: echo "This is a PR"
  
  # StartsWith / EndsWith
  - name: Check feature branch
    if: ${{ startsWith(github.ref, 'refs/heads/feature/') }}
    run: echo "Feature branch"
  
  # Format
  - name: Format string
    run: echo "${{ format('Hello {0}!', github.actor) }}"
  
  # JSON
  - name: Parse JSON
    run: echo "${{ toJSON(github.event) }}"

Status Check Functions

steps:
  - name: Succeed
    run: exit 0
  
  - name: Fail
    run: exit 1
  
  # Run only if all previous steps succeeded
  - name: On success
    if: ${{ success() }}
    run: echo "Everything passed!"
  
  # Run only if any previous step failed
  - name: On failure
    if: ${{ failure() }}
    run: echo "Something failed!"
  
  # Run regardless of previous steps
  - name: Always run
    if: ${{ always() }}
    run: echo "Cleanup"
  
  # Run only if workflow was cancelled
  - name: On cancel
    if: ${{ cancelled() }}
    run: echo "Workflow was cancelled"

Service Containers

PostgreSQL:

jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    
    steps:
      - name: Run tests
        run: npm test
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_db

Redis:

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

Multiple Services:

services:
  postgres:
    image: postgres:14
    env:
      POSTGRES_PASSWORD: postgres
    ports:
      - 5432:5432
  
  redis:
    image: redis:7
    ports:
      - 6379:6379
  
  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - 5672:5672
      - 15672:15672

Matrix Strategy

jobs:
  test:
    runs-on: ${{ matrix.os }}
    
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [16, 18, 20]
        # Creates 9 jobs: 3 OS × 3 Node versions
    
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      
      - run: npm test

With includes and excludes:

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [16, 18, 20]
    include:
      # Add specific combination
      - os: ubuntu-latest
        node: 20
        experimental: true
    exclude:
      # Don't test Node 16 on Windows
      - os: windows-latest
        node: 16

My real-world matrix:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20]
        database: [postgres:14, postgres:15]
    
    services:
      postgres:
        image: ${{ matrix.database }}
    
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Complete Real-World Example

Here's my complete CI workflow for a TypeScript microservice:

name: User Service CI

on:
  push:
    branches: [main, develop]
    paths:
      - 'services/user/**'
      - 'packages/**'
      - '.github/workflows/user-ci.yml'
  pull_request:
    branches: [main, develop]
  workflow_dispatch:

env:
  NODE_VERSION: '18'
  SERVICE_PATH: services/user

defaults:
  run:
    working-directory: services/user

jobs:
  lint-and-type-check:
    name: Lint and Type Check
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: '${{ env.SERVICE_PATH }}/package-lock.json'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run ESLint
        run: npm run lint
      
      - name: TypeScript type check
        run: npm run type-check
  
  test:
    name: Test
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: user_test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
      
      redis:
        image: redis:7
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 6379:6379
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: '${{ env.SERVICE_PATH }}/package-lock.json'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Generate Prisma Client
        run: npx prisma generate
      
      - name: Run database migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/user_test
      
      - name: Run unit tests
        run: npm run test:unit
      
      - name: Run integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/user_test
          REDIS_URL: redis://localhost:6379
      
      - name: Generate coverage report
        run: npm run test:coverage
      
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        if: always()
        with:
          files: ./services/user/coverage/lcov.info
          flags: user-service
  
  build:
    name: Build
    runs-on: ubuntu-latest
    needs: [lint-and-type-check, test]
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: '${{ env.SERVICE_PATH }}/package-lock.json'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build TypeScript
        run: npm run build
      
      - name: Upload build artifacts
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: services/user/dist/
          retention-days: 7

Key Takeaways

1. YAML is whitespace-sensitive: Always use spaces, never tabs

2. Triggers are flexible: Use push, pull_request, schedule, workflow_dispatch

3. Jobs can depend on each other: Use needs to create pipelines

4. Service containers are powerful: Test with real databases easily

5. Matrix builds test multiple configurations: Test across different Node versions, OS, etc.

6. Secrets keep sensitive data safe: Never hardcode credentials

7. Expressions enable conditional logic: Run steps/jobs only when needed

In the next part, we'll dive deeper into building complete CI/CD pipelines specifically for TypeScript microservices.