Your First Workflow: Events, Jobs and Steps

What you'll build

A first workflow that runs on every push, has two jobs, and prints information about the commit. You'll learn the vocabulary every other workflow uses.

The idea

GitHub Actions runs automation in response to things that happen in your repository. A workflow is a YAML file in .github/workflows/:

• An event (on:) starts it: a push, a pull request, a schedule, a manual click.
• A job is a group of steps that runs on one fresh virtual machine called a runner (runs-on: ubuntu-latest).
• A step is either a shell command (run:) or a reusable action (uses:).
• Jobs run in parallel by default. Steps inside a job run in order, and a failing step stops that job.

Commit the file, push, and open the repository's Actions tab to see the run, its jobs and each step's log. A workflow can only run on GitHub, so every example in this course is checked with actionlint, the standard workflow linter, and the output shows what the workflow would do.

The code

name: Hello workflow
on: push

jobs:
  info:
    runs-on: ubuntu-latest
    steps:
      - name: Show commit details
        run: |
          echo "Repository: ${{ github.repository }}"
          echo "Commit:     ${{ github.sha }}"
          echo "Branch:     ${{ github.ref_name }}"

  tools:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: List the files
        run: ls -la

actionlint: no problems found
workflow: Hello workflow
triggers: push
jobs, in the order they run:
  info: runs on ubuntu-latest | 1 step(s)
  tools: runs on ubuntu-latest | 2 step(s)

Because neither job has needs:, they start at the same time on two different machines. The tools job uses actions/checkout, since a runner starts empty and does not contain your code until you check it out.

Common mistakes

• Forgetting actions/checkout. Without it the runner has no repository files.
• Wrong folder or extension. Files must be in .github/workflows/ and end in .yml or .yaml.
• YAML indentation errors. Use spaces, never tabs; a single wrong indent changes the meaning.
• Expecting steps to share a shell. Each run step starts a new shell, so a cd or export in one step is gone in the next.
• Editing on a branch but expecting a run elsewhere. push workflows run from the pushed commit's version of the file.

Key points

• A workflow is YAML in .github/workflows/, triggered by on: events.
• Jobs run in parallel on separate runners; steps run in order.
• run executes shell commands; uses runs a reusable action.
• Check out the repository yourself with actions/checkout. Further reading: GitHub Docs.