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.
In this series25 guides, you're on Your first workflow
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 withneeds. See jobs and steps. - Step: a shell command (
run:) or a reusable action (uses:) such asactions/checkout.
Your first workflow#
- Open a repository on GitHub (or create one ↗).
- Create the file
.github/workflows/hello.yml, either locally or from the Actions tab with set up a workflow yourself. - Paste this:
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-
Commit and push. Open the Actions tab: the run appears within a few seconds. Click it, then the
hellojob, to see each step’s log.No run? Check that the file sits directly in
.github/workflows/(not in a subfolder) and ends in.ymlor.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.pushruns it on every push to any branch or tag; the triggers guide shows how to narrow it down.workflow_dispatchlets 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-latestasks 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 underrun:is written for bash, the default shell on Linux and macOS. Windows runners default to PowerShell, where$GITHUB_SHAbecomes$env:GITHUB_SHA: addshell: bashto the step to run the script there unchanged.actions/checkout@v7clones your repository into the runner, fetching only the commit that triggered the run (addfetch-depth: 0underwith: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_SHAand$RUNNER_OSare default environment variables set on every runner. An expression’s value is pasted into the script text, so use expressions inrun:only for values you control: a pull request title or a branch name could inject commands. Pass such values throughenv: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:
- Basics, a suggested path from here: Triggers, then Jobs, steps and needs.
- Workflow logic: Conditions, Concurrency, Environment variables, Passing data, Matrix strategy, Parallel steps.
- Caching: Caching dependencies, Cache keys and scopes, Docker layer caching.
- Deployments, reuse and security: Environments, Triggering other workflows, pull_request vs pull_request_target.
- Troubleshooting: Debugging, No space left on device.
- Runners: runs-on, Larger runners, GPU runners, Self-hosted runners, Actions Runner Controller (ARC).