Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 44 ยท GitHub Actions Basics

Your First Workflow

Write and understand your first GitHub Actions workflow: where the file lives, name, on, jobs, runs-on, steps, uses versus run, and how to read the run log.

A workflow is a YAML file that tells GitHub Actions what to do when something happens in your repository. You add the file, push it, and GitHub starts running it on its own machines, with the results shown on the repository's Actions tab. There is nothing to install and no server to manage, which makes it the quickest way to see CI in action.

In this lesson you will write a first workflow, learn what each top-level key means, understand the difference between uses and run, and learn how to read the log of a run. GitHub Actions needs a GitHub repository, so the YAML here is read-only. To see the same mechanics, you will also run a small stand-in program that reads a simplified workflow and executes its run steps.

Where workflows live

GitHub looks for workflow files in one place only: the folder .github/workflows/ at the root of the repository. Any file there that ends in .yml or .yaml is a workflow. A repository can have as many as it wants, and each one runs independently.

TEXT
my-project/
  .github/
    workflows/
      ci.yml
      release.yml
  src/
  package.json

The workflow file must be on the branch you expect it to run for. A workflow on a feature branch that has not been merged still runs for pushes to that branch, but some triggers (such as manual runs and schedules) only work for the file on the default branch. Triggers: push, pull_request, schedule and More covers this.

The smallest useful workflow

Create .github/workflows/hello.yml:

YAML
name: Hello

on: push

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Say hello
        run: echo "Hello from GitHub Actions"
      - name: Show the machine
        run: uname -a

Commit and push this file. A few seconds later, a run named Hello appears under the Actions tab. Every part has a job:

Key Meaning
name The workflow's display name in the Actions tab. Optional; the file name is used if you omit it.
on The event(s) that start the workflow. push means "whenever commits are pushed to any branch".
jobs The jobs to run. Each key under jobs is a job ID (greet here).
runs-on The kind of machine that runs the job. ubuntu-latest is a GitHub-hosted Linux runner.
steps The ordered list of things the job does.

Each step is an item in a list (starting with a dash). A step can have a name (shown in the log) and exactly one of two actions: run or uses.

run versus uses

These two keys are the heart of every workflow.

run executes a command in a shell on the runner, exactly as if you typed it in a terminal. On Linux and macOS the default shell is Bash; on Windows it is PowerShell. Use run for your own commands such as npm test or make build. A multi-line command uses the block marker you learned in YAML for Pipeline Authors:

YAML
- name: Build and test
  run: |
    npm ci
    npm run build
    npm test

uses runs a reusable piece of automation, called an action, written by you or someone else. Its name follows the pattern owner/repository@version:

YAML
- uses: actions/checkout@v4

actions/checkout is an official action that downloads your repository's code onto the runner. The @v4 part pins a version; without a pin, a change in the action could change your pipeline behind your back. An action can take inputs through with::

YAML
- uses: actions/setup-node@v4
  with:
    node-version: 22

Here setup-node installs Node.js 22 on the runner. In general, use uses when someone has already solved the task well (installing a language, caching, uploading artifacts) and run for everything specific to your project.

A fresh runner starts empty. It does not contain your code. If your job runs npm test without an earlier actions/checkout step, it will fail because there is no package.json to read. Nearly every job starts with checkout.

A realistic first workflow

Putting the pieces together gives the typical shape of a CI workflow for a Node.js project:

YAML
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: 22

      - name: Install dependencies
        run: npm ci

      - name: Run the tests
        run: npm test

The on block now lists two triggers with details: pushes to main, and pull requests (for any branch). When someone opens a pull request, this workflow runs and reports its result on the pull request page. If a step fails, the later steps are skipped, the job turns red, and the pull request shows a failed check. Chapter 6 shows how to make that check mandatory before merging.

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant R as Runner
    Dev->>GH: git push (workflow file + code)
    GH->>GH: Match the push to on: triggers
    GH->>R: Start job on a fresh runner
    R->>R: checkout, setup-node, npm ci, npm test
    R-->>GH: Logs and result (pass or fail)
    GH-->>Dev: Check mark or red cross

From push to result: GitHub matches the event to your workflow, hands the job to a clean runner, and reports the outcome.

Reading the run log

Open the Actions tab, click the run, then click the job. You will see every step as a collapsible section, with a green check, a red cross, or a skipped marker. Some things to know:

  • Set up job and Complete job are extra steps that GitHub adds. The first shows the runner image and the versions of the actions used.
  • Each step's log shows the command first, then its output, then (if you use uses) the inputs the action received.
  • A failing step shows the output just before the error, in red. Scroll up inside that step first, since the real cause is often a few lines above the last line.
  • Steps that were skipped because an earlier one failed are shown dimmed.
  • The run's Summary page lists annotations (warnings and errors from tools), artifacts and a timing view.

You can also re-run a failed job from the run page, and you can enable more detailed logging when you need it (see Debugging Failing Pipelines).

A stand-in workflow runner

The real runner is a GitHub-operated virtual machine, and the real uses actions are downloaded from GitHub. Neither is available on this website. The program below is a stand-in that shows the logic: it parses a simplified workflow, prints each step the way the log does, runs the run commands in a real shell on this page's sandbox, and stops at the first non-zero exit code. It treats uses: as a step it merely announces. It does not implement real YAML, contexts, matrices or most workflow keys.

Node.js Run a simplified workflow

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the sh -e flag. Real runners run run: scripts with Bash in a mode that stops at the first failing command (bash -e), so a multi-line script does not keep going after a failure. The third step prints "first" and "second", the fourth prints and then exits with code 3, and the final step is skipped, matching what the run log would show.

Common beginner mistakes

  • The file is in the wrong folder. It must be exactly .github/workflows/, with the dot and the s.
  • Indentation errors. The Actions tab reports "Invalid workflow file" with the line number; see the YAML lesson.
  • No checkout. Jobs that need your code must run actions/checkout.
  • Unpinned or misspelled actions. actions/checkout@v4 works; actions/chekout@v4 fails with "Unable to resolve action".
  • Expecting files to persist between jobs. They do not; each job gets a new runner (Anatomy of a Pipeline).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where must a GitHub Actions workflow file be stored?

    GitHub only looks for workflows in the .github/workflows/ folder. Files elsewhere are ignored.
  2. 2. What is the difference between run and uses in a step?

    run executes commands in a shell on the runner. uses runs a packaged action identified as owner/repo@version, optionally with inputs under with.
  3. 3. Your job runs npm test and fails because package.json is missing. What is the most likely cause?

    A fresh runner is empty. Add actions/checkout before steps that need your repository's files.
  4. 4. A step in the middle of a job exits with code 1. What happens to the later steps by default?

    By default the first failing step stops the job. Later steps are skipped, unless a step is explicitly told to run even after a failure.
  5. 5. Why pin an action version, as in actions/checkout@v4?

    Pinning to a version tag (or, for the highest safety, a full commit SHA) keeps pipeline behaviour stable and limits supply-chain risk.

Summary

  • Workflows are YAML files in .github/workflows/; each has a name, an on trigger, and one or more jobs.
  • A job has a runs-on machine and a list of steps; steps run in order and the first failure stops the job.
  • Use run for shell commands and uses for reusable actions such as actions/checkout@v4; give actions inputs with with.
  • Fresh runners are empty, so start jobs with checkout, and pin action versions.
  • Read a run from the Actions tab: expand steps, look at the lines above the failure, and note which steps were skipped.

Next: Triggers: push, pull_request, schedule and More