quickstart →

Your first GitHub Actions workflow

What GitHub Actions is and how a workflow file works: on, jobs, runs-on and steps, with a first workflow you can copy, run, and extend.

GitHub Actions is GitHub’s built-in platform for CI/CD (continuous integration and continuous delivery) and other automation. It runs commands for you when something happens in a repository: tests on every push, a deploy when a pull request merges, a report every Monday. The instructions live in YAML files under .github/workflows/, versioned with your code.

The four words to know#

  • Workflow: one YAML file in .github/workflows/. A repository can have many.
  • Event (on:): what starts the workflow, such as a push, a pull request, a schedule or a button click. See triggers.
  • Job: a set of steps that runs on one machine, the runner, picked with runs-on:. Jobs run in parallel unless you chain them with needs. See jobs and steps.
  • Step: a shell command (run:) or a reusable action (uses:) such as actions/checkout.

Your first workflow#

  1. Open a repository on GitHub (or create one ↗).
  2. Create the file .github/workflows/hello.yml, either locally or from the Actions tab with set up a workflow yourself.
  3. Paste this:
.github/workflows/hello.yml
name: Hello
on:
push:
workflow_dispatch: # adds a "Run workflow" button
jobs:
hello:
runs-on: ubuntu-latest
steps:
- name: Check out the code
uses: actions/checkout@v7
- name: Say hello
run: |
echo "Hello from ${{ github.repository }}"
echo "Commit $GITHUB_SHA on $RUNNER_OS"
ls -la
  1. Commit and push. Open the Actions tab: the run appears within a few seconds. Click it, then the hello job, to see each step’s log.

    No run? Check that the file sits directly in .github/workflows/ (not in a subfolder) and ends in .yml or .yaml, and that Actions is enabled under Settings → Actions → General. If GitHub can’t parse the file, no job runs: the run shows up as failed, with the error at the top. The debugging guide lists other causes.

Line by line:

  • on: lists the events that start the workflow. push runs it on every push to any branch or tag; the triggers guide shows how to narrow it down. workflow_dispatch lets you start it by hand with a Run workflow button, which GitHub shows only once the file is on the default branch.
  • runs-on: ubuntu-latest asks for a fresh Ubuntu virtual machine. GitHub also offers Windows (windows-latest), macOS (macos-latest) and Linux on Arm (ubuntu-24.04-arm). The machine is thrown away when the job ends. The script under run: is written for bash, the default shell on Linux and macOS. Windows runners default to PowerShell, where $GITHUB_SHA becomes $env:GITHUB_SHA: add shell: bash to the step to run the script there unchanged.
  • actions/checkout@v7 clones your repository into the runner, fetching only the commit that triggered the run (add fetch-depth: 0 under with: when a step needs the history or tags). Without checkout, the job starts with an empty directory.
  • ${{ github.repository }} is an expression, replaced before the step runs. $GITHUB_SHA and $RUNNER_OS are default environment variables set on every runner. An expression’s value is pasted into the script text, so use expressions in run: only for values you control: a pull request title or a branch name could inject commands. Pass such values through env: and read them as "$VAR".

What runs-on means#

runs-on picks the machine a job runs on, with one or more labels. ubuntu-latest is a GitHub-hosted runner; a list such as [self-hosted, linux, x64] targets your own machines; a runner group can be selected with group:. The runs-on guide covers every form, including choosing the runner from a matrix or an expression.

The runner decides speed and cost: standard GitHub-hosted Linux runners have 2 vCPUs for private repositories (4 for public ones) and are billed by the minute. Larger runners and self-hosted runners are the two ways to go bigger.

Public vs private repositories#

Standard GitHub-hosted runners are free and unlimited in public repositories. In private repositories they draw from your plan’s included compute, a monthly pool for the whole account rather than for each repository. Since October 2026, that pool is a dollar amount, not a number of minutes: $12 on GitHub Free, $18 on Pro and Team, $300 on Enterprise Cloud. On GitHub Free, that buys about 2,000 minutes on standard Linux ($0.006 a minute), but only about 1,200 on Windows ($0.010) or 190 on macOS ($0.062). Once the pool is used up, you pay per minute if a payment method is on file; otherwise jobs are blocked until the next billing cycle. Self-hosted runners don’t use the included compute. For larger runners, see how they are billed. Every rate and plan allowance is in GitHub Actions pricing.

Where to go next#

Each guide stands alone, so you can read them in any order. Here they are by group, as on the GitHub Actions guides index: