GitHub Actions cheatsheet

Common triggers

YAML	When it runs
`on: push`	Any push to matching branches
`on: pull_request`	PR opened, sync, reopen
`on: schedule`	Cron (UTC only)
`on: workflow_dispatch`	Manual run from UI
`paths: ['src/**']`	Only when listed paths change

Secrets and variables

# Repository secret (Settings → Secrets)
env:
  API_KEY: ${{ secrets.MY_API_KEY }}

# Repository variable (non-secret)
env:
  REGION: ${{ vars.AWS_REGION }}

# Job-level permissions
permissions:
  contents: read
  packages: write

Matrix build

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

Docker build and push

      - uses: docker/login-action@v3
        with:
          registry: harbor.example.com
          username: ${{ secrets.HARBOR_USER }}
          password: ${{ secrets.HARBOR_PASS }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: harbor.example.com/app:${{ github.sha }}

Cache and artifacts

Feature	Typical use
`actions/cache@v4`	npm, pip, Gradle caches
`actions/upload-artifact@v4`	Test reports, binaries between jobs
`actions/download-artifact@v4`	Consume artifact in downstream job

Job chaining

jobs:
  build:
    runs-on: ubuntu-latest
    steps: [...]
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: production
    steps: [...]

gh CLI (local debugging)

gh run list --workflow=ci.yml
gh run view RUN_ID --log
gh run watch RUN_ID
gh workflow run ci.yml --ref main

Useful context expressions

Expression	Description
`github.sha`	Commit SHA that triggered the run
`github.ref`	Branch or tag ref
`github.event.pull_request.number`	PR number (on pull_request)
`runner.os`	Linux, Windows, macOS

Pro tips

Pin actions to a full commit SHA for supply-chain safety, not only @v4
Enable debug logging temporarily: set repo secret ACTIONS_STEP_DEBUG=true
Fork PRs get read-only GITHUB_TOKEN — use pull_request_target carefully
Path filters on push do not apply to workflow_dispatch
Hosted runner clocks are UTC — cron schedules too