liminfo

GitHub Actions Reference

Free reference guide: GitHub Actions Reference

30 results

About GitHub Actions Reference

The GitHub Actions Reference is a searchable YAML syntax cheat sheet for GitHub Actions workflow files stored in .github/workflows/. It covers six key areas: Workflow-level configuration (name, file location, permissions, global env variables, concurrency control to cancel redundant runs), Trigger events (on: push with branch and path filters, pull_request events, cron schedules, manual workflow_dispatch with input parameters, workflow_call for reusable workflows), Job definitions (jobs block, runs-on for Ubuntu/macOS/Windows runners, needs for job dependencies, if conditions for conditional execution, service containers like postgres and redis), Step directives (uses for third-party actions like actions/checkout@v4 and actions/setup-node@v4, run for shell commands, with for action parameters, github context variables, step output references), Secrets and variables (${{ secrets.NAME }}, GITHUB_TOKEN, ${{ vars.NAME }}, environment-scoped secrets), and Matrix strategy (multi-dimensional build matrices, include/exclude combinations, fail-fast behavior, max-parallel limits).

GitHub Actions is the CI/CD platform built directly into GitHub, used by millions of open-source and enterprise development teams worldwide. Frontend developers use it to automate npm builds and Vitest tests on pull requests. Backend engineers use it to build Docker images and deploy to cloud platforms. DevOps teams configure matrix builds to test across multiple Node.js versions and operating systems simultaneously. The reusable workflow_call trigger enables DRY pipeline architecture across repositories.

Every entry in this reference shows the exact YAML key, a concise description, and a complete YAML block with real values that can be copied into a workflow file. The reference covers practical patterns like running jobs only on the main branch using if conditions, passing data between steps using $GITHUB_OUTPUT, canceling in-progress runs with concurrency groups, and testing across multiple environments with strategy: matrix — all organized into six filterable categories.

Key Features

  • Workflow config: name, .github/workflows path, permissions (contents/packages/pull-requests), env, concurrency with cancel-in-progress
  • Triggers: on: push (branches/paths), pull_request (types), schedule (cron), workflow_dispatch (inputs), workflow_call (reusable)
  • Jobs: jobs block, runs-on (ubuntu/macos/windows), needs for dependencies, if for conditionals, services (postgres/redis)
  • Steps: uses (actions/checkout@v4, setup-node@v4), run (shell commands), with (action inputs), github context variables
  • Step outputs: ${{ steps.id.outputs.name }} pattern, $GITHUB_OUTPUT environment file for passing values between steps
  • Secrets and variables: ${{ secrets.NAME }}, auto-provisioned GITHUB_TOKEN, ${{ vars.NAME }}, environment-scoped secrets
  • Matrix strategy: multi-dimensional os/node-version matrices, include/exclude combinations, fail-fast, max-parallel
  • Concurrency groups to cancel redundant runs, permissions scoping for secure workflows

Frequently Asked Questions

What is GitHub Actions and where do workflow files go?

GitHub Actions is GitHub's built-in CI/CD platform. Workflow files are YAML files stored in the .github/workflows/ directory at the root of your repository. GitHub automatically detects and runs these workflows based on the trigger events you define. Each repository can have multiple workflow files, each handling different automation scenarios.

What is the difference between on: push and on: pull_request triggers?

on: push runs the workflow whenever commits are pushed to the specified branches. on: pull_request runs the workflow when a pull request is opened, synchronized (new commits pushed), or reopened against the specified branches. You can further filter both triggers with types: and paths: to only run the workflow for specific file changes or PR event types.

How do I pass data from one step to another in GitHub Actions?

Use the $GITHUB_OUTPUT environment file. In the source step, set an id and write name=value to $GITHUB_OUTPUT using echo "name=value" >> $GITHUB_OUTPUT. In subsequent steps, reference the value using ${{ steps.step-id.outputs.name }}. This mechanism replaced the deprecated set-output command and is the current recommended approach.

What is GITHUB_TOKEN and how do I use it?

GITHUB_TOKEN is an automatically created secret that GitHub provides to every workflow run. It has permissions to act on the repository where the workflow runs, such as creating comments on pull requests, pushing to the repository, or publishing packages. Access it with ${{ secrets.GITHUB_TOKEN }}. Its permissions are controlled by the permissions: block in your workflow.

How does the matrix strategy work in GitHub Actions?

strategy: matrix lets you run a job across multiple combinations of values. Define one or more dimension arrays under matrix: (e.g. node-version: [18, 20, 22] or os: [ubuntu-latest, macos-latest]). GitHub creates a separate job for each combination. Use include: to add specific combinations and exclude: to remove them. Set fail-fast: false to allow all matrix jobs to complete even if one fails.

How do I run a workflow job only on the main branch?

Add an if: condition at the job level: if: github.ref == 'refs/heads/main'. This prevents the job from running on feature branches or pull requests. You can combine conditions with && and || operators. For deploy jobs, also consider using the environment: key to require manual approval before the job runs.

What is the concurrency key used for in GitHub Actions?

concurrency: controls how multiple workflow runs triggered for the same branch or PR interact with each other. Setting concurrency.group to a string that includes github.ref ensures only one run per branch is active. Adding cancel-in-progress: true automatically cancels the previous run when a new one starts, preventing redundant CI runs from piling up on rapid-fire commits.

What is the difference between workflow_dispatch and workflow_call?

workflow_dispatch adds a "Run workflow" button to the GitHub UI and API, allowing manual triggering with optional input parameters. workflow_call makes the workflow reusable — other workflows in the same or different repositories can call it using the uses: key, passing inputs and receiving outputs. workflow_call is the recommended pattern for sharing pipeline logic across multiple repositories.