GitHub Actions Reference

Triggers the workflow on a push to a branch or tag. Can be scoped by branches, tags, and path filters.

on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**'

Triggers on pull request activity. The default activity types are opened, synchronize, and reopened.

on:
  pull_request:
    types: [opened, reopened, synchronize]
    branches: [main]

Allows manual triggering from the GitHub UI or API. Inputs can be defined for user-supplied values.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target env'
        required: true
        default: staging

Triggers the workflow on a cron schedule (UTC). Minimum interval is 5 minutes.

on:
  schedule:
    - cron: '0 2 * * 1-5'  # 02:00 UTC weekdays

Allows this workflow to be called as a reusable workflow from another workflow. Supports inputs and secrets.

on:
  workflow_call:
    inputs:
      deploy_env:
        required: true
        type: string

Triggers on GitHub Release events. Useful for publish/deploy pipelines.

on:
  release:
    types: [published]

Specifies the runner environment. Use ubuntu-latest, windows-latest, macos-latest, or a self-hosted label.

jobs:
  build:
    runs-on: ubuntu-latest

Declares job dependencies. The current job will not run until all listed jobs complete successfully.

jobs:
  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest

Creates multiple job runs across a combination of variables. Use matrix.<KEY> to reference values in steps.

strategy:
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, windows-latest]

Associates the job with a deployment environment. Enables protection rules and environment-scoped secrets.

jobs:
  deploy:
    environment:
      name: production
      url: https://example.com

Defines outputs that can be consumed by downstream jobs using needs.<JOB>.outputs.<NAME>.

jobs:
  build:
    outputs:
      version: ${{ steps.get_ver.outputs.version }}
    steps:
      - id: get_ver
        run: echo "version=1.2.3" >> $GITHUB_OUTPUT

Restricts or grants GITHUB_TOKEN permissions for the job. Values are read, write, or none.

permissions:
  contents: read
  packages: write
  id-token: write

References a reusable action from a repo, Docker image, or local path. Versioned with @tag or @sha.

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'

Runs a shell command. Supports multi-line strings. Default shell is bash on Linux/macOS, pwsh on Windows.

steps:
  - name: Build
    run: |
      npm ci
      npm run build

Passes input parameters to an action. The parameters are defined in the action's action.yml.

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

Conditionally runs a step. Evaluates a GitHub Actions expression. Use always() to run even if previous steps failed.

- name: Deploy
  if: github.ref == 'refs/heads/main' && success()
  run: ./deploy.sh

Allows the workflow to continue if this step fails. The step's outcome is still recorded.

- name: Optional check
  continue-on-error: true
  run: npm run optional-check

Contains information about the workflow run. Key properties: event_name, ref, sha, actor, repository, run_id, run_number.

- run: echo "Actor: ${{ github.actor }} SHA: ${{ github.sha }}"

Provides access to env vars set in the workflow, job, or step level via the env: key.

env:
  NODE_ENV: production
steps:
  - run: echo ${{ env.NODE_ENV }}

Access encrypted secrets defined in the repo, environment, or organization settings.

- uses: actions/deploy@v1
  with:
    token: ${{ secrets.DEPLOY_TOKEN }}

Access outputs from previous steps in the same job using their id field.

- id: build
  run: echo "sha=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
- run: echo ${{ steps.build.outputs.sha }}

Information about the runner executing the job: name, os, arch, temp, tool_cache.

- run: echo "OS: ${{ runner.os }} Arch: ${{ runner.arch }}"

Built-in functions: contains(), startsWith(), endsWith(), format(), join(), toJSON(), fromJSON(), hashFiles(), always(), success(), failure(), cancelled().

- if: contains(github.event.pull_request.labels.*.name, 'deploy')
  run: ./deploy.sh