Skip to content

Workflow Syntax

GitHub Actions workflows are defined using YAML files in the .github/workflows/ directory. These files describe the structure of the workflow, including triggers, jobs, steps, and environment variables. Understanding the syntax is critical for configuring reliable CI/CD pipelines.

Triggers and Events

Workflows are triggered by events such as push, pull_request, or custom webhooks. Events are specified under the on key.

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
- Use events for GitHub-native triggers (e.g., push, pull_request).
- For external triggers, use workflow_dispatch with a UI button or repository_dispatch for custom payloads.
- Nested keys (e.g., branches, paths) filter which branches or files trigger the workflow.

Jobs and Runners

Jobs are units of work that run on a runner (virtual machine or self-hosted). Each job must specify a runner with runs-on.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
- runs-on defines the runner type (e.g., ubuntu-latest, windows-latest, or a self-hosted runner).
- Jobs can have conditions using if to control execution (e.g., if: ${{ github.event_name == 'push' }}).
- Jobs can be parallelized using strategy for matrix builds.

Steps and Actions

Steps are individual tasks within a job. They can be built-in actions, custom scripts, or third-party tools.

steps:
  - name: Install dependencies
    run: npm install
  - name: Run tests
    uses: actions/setup-node@v3
    with:
      node-version: '18'
- run executes shell commands (supports bash, PowerShell, etc.).
- uses invokes actions from the GitHub Marketplace or local paths.
- Inputs are passed via the with keyword for actions.
- Steps can be conditionally skipped using if or continue-on-failure.

Environment Variables

Environment variables are defined under env and can be scoped to the workflow, job, or step.

env:
  API_URL: https://api.example.com
  DEBUG: false

jobs:
  deploy:
    env:
      DEBUG: true
    steps:
      - run: echo "DEBUG: ${{ env.DEBUG }}"
- Variables are accessed using ${{ env.VARIABLE }} in scripts.
- Secrets (sensitive variables) are stored in the repository settings and referenced via ${{ secrets.SECRET_NAME }}.
- Variables can override defaults at different scopes (workflow > job > step).

Key takeaways

  • Workflows are structured using on, jobs, and steps keys.
  • Triggers define when workflows execute, with optional event filters.
  • Jobs run on runners and can include conditional logic.
  • Steps combine built-in actions, scripts, and custom tools.
  • Environment variables and secrets enable dynamic configuration.