act-workflow-syntax

Act - GitHub Actions Workflow Syntax

Use this skill when creating or modifying GitHub Actions workflow files (.github/workflows/*.yml). This covers workflow structure, triggers, jobs, steps, and best practices for workflows that work both on GitHub and locally with act.

Workflow File Structure

Every GitHub Actions workflow follows this basic structure:

name: Workflow Name
user-invocable: false
on: [push, pull_request]  # Triggers

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Step name
        run: echo "Commands here"

Top-Level Fields

• name: Human-readable workflow name (optional but recommended)
• on: Trigger events (push, pull_request, workflow_dispatch, etc.)
• env: Environment variables available to all jobs
• jobs: Map of job definitions
• permissions: Token permissions for the workflow

Workflow Triggers

Event Triggers

# Single event
on: push

# Multiple events
on: [push, pull_request]

# Event with filters
on:
  push:
    branches:
      - main
      - 'releases/**'
    paths:
      - '**.js'
      - '!docs/**'
  pull_request:
    types: [opened, synchronize, reopened]

Manual Triggers

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

Schedule Triggers

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

Job Configuration

Basic Job

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

Job with Environment Variables

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      NODE_ENV: production
      API_URL: ${{ secrets.API_URL }}
    steps:
      - run: echo "Deploying to $NODE_ENV"

Job Dependencies

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

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - run: npm run deploy

Matrix Builds

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
      fail-fast: false
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Steps

Using Actions

steps:
  # Checkout code
  - uses: actions/checkout@v4

  # Setup Node.js
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  # Upload artifacts
  - uses: actions/upload-artifact@v4
    with:
      name: dist
      path: dist/

Running Commands

steps:
  # Single line
  - run: npm install

  # Multi-line
  - run: |
      npm ci
      npm run build
      npm test

  # With name
  - name: Install dependencies
    run: npm ci

  # With working directory
  - run: npm test
    working-directory: ./packages/core

  # With shell
  - run: echo "Hello"
    shell: bash

Conditional Steps

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main'
    run: npm run deploy

  - name: Run on success
    if: success()
    run: echo "Previous steps succeeded"

  - name: Run on failure
    if: failure()
    run: echo "A step failed"

  - name: Always run
    if: always()
    run: echo "Runs regardless of status"

Expressions and Contexts

Common Contexts

steps:
  - run: echo "Event: ${{ github.event_name }}"
  - run: echo "Branch: ${{ github.ref_name }}"
  - run: echo "SHA: ${{ github.sha }}"
  - run: echo "Actor: ${{ github.actor }}"
  - run: echo "Job status: ${{ job.status }}"
  - run: echo "Runner OS: ${{ runner.os }}"

Using Secrets

steps:
  - run: echo "Token is set"
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      API_KEY: ${{ secrets.API_KEY }}

Functions

steps:
  - if: contains(github.event.head_commit.message, '[skip ci]')
    run: echo "Skipping CI"

  - if: startsWith(github.ref, 'refs/tags/')
    run: echo "This is a tag"

  - if: endsWith(github.ref, '/main')
    run: echo "This is main branch"

  - run: echo "${{ format('Hello {0}', github.actor) }}"

Act-Specific Considerations

Testing Locally with Act

# Run all workflows
act

# Run specific event
act push

# Run specific job
act -j build

# Dry run (validate without executing)
act --dryrun

# List workflows
act -l

# Use specific platform
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Environment Variables for Act

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check environment
        run: |
          if [ "$ACT" = "true" ]; then
            echo "Running in act"
          else
            echo "Running on GitHub"
          fi

Secrets with Act

Create .secrets file for local testing:

GITHUB_TOKEN=ghp_your_token_here
API_KEY=your_api_key_here

Then run:

act --secret-file .secrets

Or pass secrets individually:

act -s GITHUB_TOKEN=ghp_token -s API_KEY=key

Best Practices

DO

✅ Use semantic job and step names ✅ Pin action versions (actions/checkout@v4) ✅ Use fail-fast: false for matrix builds to see all results ✅ Set appropriate timeout-minutes for jobs ✅ Use working-directory instead of cd commands ✅ Test workflows locally with act --dryrun before pushing ✅ Use caching for dependencies ✅ Use environments for deployment jobs

DON'T

❌ Hardcode secrets in workflow files ❌ Use latest tags for actions ❌ Run workflows on every file change (use path filters) ❌ Create overly complex workflows (split into multiple files) ❌ Ignore act compatibility when using GitHub-specific features ❌ Forget to validate YAML syntax

Common Patterns

Build and Test

name: CI
user-invocable: false
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - run: npm run build

Deploy on Tag

name: Deploy
user-invocable: false
on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
      - run: echo "Deploying ${{ steps.version.outputs.VERSION }}"

Monorepo with Changed Files

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      api: ${{ steps.changes.outputs.api }}
      web: ${{ steps.changes.outputs.web }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: changes
        with:
          filters: |
            api:
              - 'packages/api/**'
            web:
              - 'packages/web/**'

  build-api:
    needs: detect-changes
    if: needs.detect-changes.outputs.api == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building API"

Related Skills

• act-local-testing: Testing workflows locally before pushing
• act-docker-setup: Configuring Docker environments for act
• act-secrets-management: Managing secrets for local testing