Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท GitHub Actions

GitHub Actions: Your First Workflow

Write your first GitHub Actions workflow: the YAML file, events that trigger it, jobs, steps and where to read the logs. Includes a trigger matcher you can run.

GitHub Actions is the automation system built into GitHub. You describe what should happen in a YAML file, store that file in your repository, and GitHub runs it on its own servers whenever something interesting occurs: a push, a pull request, a new issue, a schedule, or a button press. Typical uses are running tests, building a site, publishing a package, labelling issues and deploying an app.

Actions cannot run inside this website, so the workflow files below are read-only. To make the ideas concrete, each lesson also has a small JavaScript stand-in that models one piece of the system (for example "which events start which workflow"). The stand-ins are teaching tools written by us. They are not GitHub's real engine, and they say so in their titles.

The anatomy of a workflow

A workflow is a YAML file in the folder .github/workflows/ at the root of your repository. The file name is free (ci.yml, deploy.yaml), but the extension must be .yml or .yaml. A repository can hold many workflows, and each one runs independently.

YAML
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Say hello
        run: echo "Hello from GitHub Actions"

Read it from the top:

  • name is the label shown on the Actions tab. It is optional; without it GitHub shows the file path.
  • on lists the events that start the workflow. Here: a push to main, and any pull request activity.
  • jobs is a map of named jobs. This workflow has one job called test.
  • runs-on chooses the machine type (the runner). ubuntu-latest is a GitHub-hosted Linux virtual machine.
  • steps is an ordered list. A step either runs a shell command (run) or uses a reusable action (uses).

The first step, actions/checkout, downloads your repository onto the runner. The runner starts empty, so without checkout your code is simply not there. This is the most common beginner surprise.

Each job runs on a fresh, clean virtual machine that is thrown away afterwards. Nothing you install or create in one run is still there in the next, unless you save it explicitly (see caching and artifacts).

Events: what starts a workflow

The on key accepts a single event, a list, or a map with filters. The most important events:

Event Fires when
push commits are pushed to a branch or a tag is pushed
pull_request a pull request is opened, updated or reopened (default activity types)
workflow_dispatch someone presses Run workflow or calls the API
schedule a cron time arrives (UTC)
release a release is created, published or edited
issues, issue_comment issue activity
workflow_call another workflow calls this one (reusable workflows)

Filters narrow an event. For push and pull_request you can use branches, tags and paths (and their -ignore versions):

YAML
on:
  push:
    branches: [main, "release/**"]
    paths:
      - "src/**"
      - "package.json"
  schedule:
    - cron: "30 4 * * 1"   # every Monday at 04:30 UTC
  workflow_dispatch:
    inputs:
      environment:
        description: "Where to deploy"
        required: true
        default: staging

The paths filter is a great way to save minutes: a docs-only change need not run the whole test suite. Patterns use glob syntax where * matches within one folder and ** matches across folders.

From event to result

Event push, PR, schedule
Workflow YAML in .github/workflows
Runner Fresh VM per job
Result Checks and logs

Events pick workflows; workflows start jobs; jobs run on runners.

1 / 2

A stand-in: which workflows would fire?

The real engine reads all your workflow files, compares the incoming event with each on section, and starts the matching ones. The stand-in below models only the branch and path filters, using a simplified glob. It is a learning aid, not GitHub's matcher: GitHub's glob rules have more cases than we implement.

JS Stand-in: trigger matcher (not GitHub's engine)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try adding a tags rule or changing the globs and watch which workflows start.

Reading a run

Open the Actions tab of your repository. The left column lists your workflows; the main area lists runs, newest first. Click a run to see its jobs, then click a job to read the log of each step. Failed steps are marked with a red cross and expand automatically. Each log line can be linked to directly, and you can re-run a single failed job, or all jobs, from the top-right menu.

For pull requests, the results also appear at the bottom of the pull request as checks. A required check that fails blocks merging once you configure branch protection or rulesets.

Using actions in steps

uses: owner/repo@ref runs an action published in a repository. The ref after @ is a tag, a branch or a commit SHA. Many actions take inputs through with:

YAML
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 22
  - run: npm ci
  - run: npm test

run steps execute in a shell (bash on Linux and macOS, PowerShell on Windows by default). A multi-line command uses a YAML block scalar:

YAML
- name: Build and report
  run: |
    npm run build
    ls -la dist

Any step that exits with a non-zero status fails, and by default a failed step stops the rest of its job.

Common mistakes

  • YAML indentation. Two spaces per level, never tabs. A mis-indented steps is the top cause of "Invalid workflow file" errors.
  • A file in the wrong folder. It must be .github/workflows/ (singular .github, plural workflows).
  • Forgetting checkout. Commands like npm test then fail with "no package.json".
  • Quoting cron or version values. node-version: 22 is fine, but 3.10 unquoted becomes the number 3.1; write "3.10".
  • Expecting a workflow from a branch to run before it is merged. For push, GitHub uses the workflow file from the pushed commit; for schedule and workflow_dispatch it uses the default branch.

Add workflow_dispatch: to every workflow while developing. It gives you a Run workflow button, so you can test without pushing dummy commits.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where must workflow files live?

    GitHub only looks for workflows in the .github/workflows folder.
  2. 2. A job runs npm test but fails with 'package.json not found'. What is the most likely cause?

    A runner starts empty; checkout downloads your repository onto it.
  3. 3. Which event gives you a manual Run workflow button?

    workflow_dispatch makes the workflow runnable by hand from the UI or API.
  4. 4. What does a paths filter on push do?

    paths restricts the trigger to pushes that touch matching files, saving needless runs.

Summary

  • A workflow is a YAML file in .github/workflows/; it has events (on), jobs, and steps.
  • Each job gets a fresh runner, so check out your code first.
  • Filters (branches, tags, paths) and workflow_dispatch make triggers precise and testable.
  • Read results on the Actions tab and as checks on pull requests.

Next: Jobs, Steps, Runners and Matrices