GitHub Actions reference

GitHub Actions workflows live under `.github/workflows/*.yml`. Every workflow is a YAML document with three required top-level pieces: a `name:`, a set of triggers under `on:`, and a map of `jobs:`. Each job declares the runner image (`runs-on:`), an optional list of dependencies (`needs:`), and a list of steps. Steps are either a shell command (`run:`) or a reusable Action (`uses: org/action@version`).

Expressions in GitHub Actions use the `${{ ... }}` syntax and pull values from contexts: `github` (repository / event metadata), `secrets` (repository / org-level secrets), `vars` (variables), `env` (environment), and `matrix` (when inside a matrix job).

Top-level keys

Key	Purpose
name	Display name of the workflow.
on	Trigger configuration: push, pull_request, schedule, workflow_dispatch, etc.
permissions	GITHUB_TOKEN scopes for the workflow.
env	Workflow-level environment variables.
concurrency	Group + cancel-in-progress controls.
jobs	Map of job-id → job definition.
jobs.<id>.runs-on	Runner label or self-hosted matcher.
jobs.<id>.steps	Ordered list of run / uses steps.
jobs.<id>.strategy.matrix	Matrix expansion of the job.
jobs.<id>.environment	Deployment environment (with required-reviewer gating).
jobs.<id>.container	Run all steps inside this Docker image.
jobs.<id>.services	Sidecar service containers (e.g. postgres).

Minimal example

name: CI
on:
  push:
    branches: [main]
  pull_request:

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

Context variables

The same concept goes by a different name on every platform. Use this table when porting expressions and conditions.

Concept	GitHub Actions	GitLab CI	CircleCI	Bitbucket
Branch name	github.ref_name	$CI_COMMIT_REF_NAME	<< pipeline.git.branch >>	$BITBUCKET_BRANCH
Commit SHA	github.sha	$CI_COMMIT_SHA	<< pipeline.git.revision >>	$BITBUCKET_COMMIT
Tag name	github.ref_name	$CI_COMMIT_TAG	<< pipeline.git.tag >>	$BITBUCKET_TAG
Repository slug	github.repository	$CI_PROJECT_PATH	<< pipeline.project.git_url >>	$BITBUCKET_REPO_FULL_NAME
Run / pipeline id	github.run_id	$CI_PIPELINE_ID	<< pipeline.id >>	$BITBUCKET_BUILD_NUMBER
Triggering event	github.event_name	$CI_PIPELINE_SOURCE	<< pipeline.trigger_source >>	(implicit; check pipelines.* section)
Actor / user	github.actor	$GITLAB_USER_LOGIN	$CIRCLE_USERNAME	$BITBUCKET_STEP_TRIGGERER_UUID
Workspace path	github.workspace	$CI_PROJECT_DIR	$CIRCLE_WORKING_DIRECTORY	$BITBUCKET_CLONE_DIR
PR / MR source branch	github.head_ref	$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME	$CIRCLE_BRANCH (head ref)	$BITBUCKET_PR_DESTINATION_BRANCH (target only)
PR / MR target branch	github.base_ref	$CI_MERGE_REQUEST_TARGET_BRANCH_NAME	(not directly exposed)	$BITBUCKET_PR_DESTINATION_BRANCH

Related Tools

data_object

YAML Formatter

Format and validate YAML. Convert YAML to JSON or JSON to YAML. Supports 2 and 4 space indentation.

timer

Cron Builder

Visual builder for cron-job schedules.

filter_list_off

Gitignore Generator

Generate .gitignore files for any language, framework, or IDE — 100+ templates, 100% client-side.

schema

JSON Schema Generator

Generate a JSON Schema from one or more sample JSONs — drafts 2020-12, 2019-09, 7, 6, 4. Detects formats (date-time, email, uuid, ipv4, uri), extracts $defs, validates with AJV, and exports to YAML, TypeScript, and Zod. 100% in your browser.

auto_awesome

AI Coding Rules

Curated rules-file library and generator for Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, Aider, Continue, and Cody. Browse 20 hand-crafted .cursorrules / CLAUDE.md / copilot-instructions.md files for popular stacks, build a custom one with the wizard, or convert any rules file between AI-tool formats.