Skip to content
Velloreth
Developer Tools 4 min read

GitHub Actions Basics: Workflows, Jobs and Steps

GitHub Actions runs your CI in the repository. Learn the workflow syntax, the job graph, caching, and the security rules that matter.

By

What a workflow is

A workflow is a YAML file in .github/workflows. GitHub reads it, and when the trigger event occurs, it runs the workflow on a runner.

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: 20
          cache: npm
      - run: npm ci
      - run: npm test

The trigger is the on block. It can be a push, a pull request, a schedule, a manual dispatch, or a webhook.

The job is a unit of work on one runner. It has a runs-on and a list of steps.

The step is either a uses (an action) or a run (a shell command). Steps in a job run in order and share the filesystem.

The job graph

Jobs run in parallel by default. A workflow with three jobs starts all three at once, on separate runners.

needs sequences them. A job that declares needs: test waits for test to finish, and it is skipped if test fails.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: npm run build

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

if gates a job or a step. The condition is evaluated before the job starts, and a false condition skips it rather than failing it.

A matrix runs a job several times. It is the way to test across versions or platforms.

strategy:
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, macos-latest]

Passing data between jobs

An artifact is a file uploaded in one job and downloaded in another. It is right for a build output.

- uses: actions/upload-artifact@v4
  with:
    name: dist
    path: dist/

# In another job
- uses: actions/download-artifact@v4
  with:
    name: dist
    path: dist/

A job output is a small string. It is right for a version number or a flag.

jobs:
  version:
    runs-on: ubuntu-latest
    outputs:
      tag: ${{ steps.v.outputs.tag }}
    steps:
      - id: v
        run: echo "tag=v1.2.3" >> "$GITHUB_OUTPUT"

  release:
    needs: version
    runs-on: ubuntu-latest
    steps:
      - run: echo "Releasing ${{ needs.version.outputs.tag }}"

$GITHUB_OUTPUT is the modern way to set an output. The older ::set-output syntax is deprecated.

Caching

A cache hit turns a multi-minute install into a few seconds. The key must include a hash of the lockfile, so a dependency change invalidates the cache.

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: npm

For a manual cache, the key is the important part.

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

restore-keys is the fallback. A partial match restores an older cache, which is faster than a cold install even if it is not exact.

Secrets and security

A secret is available through the secrets context. It is encrypted at rest and masked in the logs.

- run: ./deploy.sh
  env:
    API_KEY: ${{ secrets.API_KEY }}

Never echo a secret. The masking is a literal string match, so a transformed value, a base64 encoding, or a substring is not masked.

Never run untrusted code with secrets. A pull_request_target trigger runs with the base repository’s secrets, and a workflow that checks out and runs the pull request’s code gives an attacker the secrets. Use pull_request for untrusted code, and require approval for a first-time contributor.

Pin an action to a commit SHA. A tag such as @v4 can be moved, and a compromised action can exfiltrate the secrets. A SHA is immutable.

- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1

Set the minimum permissions. The default token has broad permissions. Declare what the workflow needs.

permissions:
  contents: read

Common mistakes

A workflow that runs on every branch. It consumes minutes and produces noise. Scope the trigger to the branches that matter.

No cache. A cold install on every run is the most common waste of minutes.

A cache key without the lockfile hash. The cache is never invalidated, and a stale dependency is restored.

Echoing a secret. The masking does not catch a transformed value.

pull_request_target with a checkout of the pull request. This is a known secret-exfiltration pattern.

An unpinned action. A tag can be moved to a malicious commit.

A job that needs another’s files without an artifact. Jobs do not share a filesystem, so the file is not there.

A quotable summary

A GitHub Actions workflow is a YAML file in .github/workflows triggered by an event, with jobs that run in parallel on separate runners and steps that run in order within a job. Use needs to sequence jobs, an artifact or a job output to pass data, and a cache keyed on the lockfile hash to cut minutes. Pin actions to a commit SHA, declare the minimum permissions, and never run untrusted pull request code with secrets available.

For the pipeline concept, see ci-cd-pipeline-basics and for the secrets, secret-management-guide. For the broader context, gitlab-ci-basics and dependency-vulnerability-scanning.

Frequently asked questions

What is GitHub Actions in simple terms?
GitHub Actions is a continuous integration and automation service built into GitHub. You add a YAML file to .github/workflows, and GitHub runs it on a virtual machine when an event occurs, such as a push or a pull request. It is used for tests, builds, deployments and scheduled jobs.
What is the difference between a job and a step?
A job is a unit of work that runs on one runner, and it has a sequence of steps. Steps in a job run in order and share the same filesystem. Jobs run in parallel by default and do not share a filesystem, so a job that needs another's output must declare needs and pass the data explicitly.
How do I pass data between jobs?
Use an artifact, or a job output. An artifact is a file uploaded in one job and downloaded in another, which is right for a build output. A job output is a small string set in one job and read in another through needs, which is right for a version number or a flag.
How do I cache dependencies?
Use the actions/cache action, or the cache option built into actions/setup-node and similar. The key should include a hash of the lockfile, so the cache is invalidated when the dependencies change. A cache hit turns a multi-minute install into a few seconds.
Are GitHub Actions secrets safe?
They are encrypted at rest and masked in the logs, but a workflow can still leak one by printing it in a transformed form, or by running untrusted code with access to it. Never run a pull request from a fork with secrets available, and never echo a secret.
What is a self-hosted runner?
A self-hosted runner is a machine you provide that GitHub sends jobs to. It is useful for a build that needs more resources, a specific architecture, or access to a private network. It is also a security responsibility, because a job runs on your machine with your network access.