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 Velloreth
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.
Related reading
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.