GitHub Actions Tutorial: Workflows, Matrix Builds, OIDC, Docker and Reusable Workflows
What Is GitHub Actions?
GitHub Actions is CI/CD built into GitHub. A workflow is a YAML file in .github/workflows/. It runs when an event happens (push, pull request, schedule, manual). A workflow has jobs, and a job has steps that run on a runner.
text
Event (push) -> Workflow -> Job A (runner 1): step, step, step
-> Job B (runner 2): step, step (needs: A)
Your First Workflow
yaml
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.13"
cache: pip
- name: Install dependencies
run: pip install -r requirements.txt
- name: Run tests
run: pytest -q
Commit the file and push. Open the Actions tab to see the run. Pull requests show the result as a check.
Pin actions: Examples use version tags such as @v4. For maximum supply chain safety pin third-party actions to a full commit SHA. Check each action's page for its latest major version.
Common Events
| Event | Use |
push, pull_request | CI on code changes |
workflow_dispatch | Manual run with optional inputs |
schedule (cron) | Nightly jobs, dependency checks |
release | Publish on a new release |
workflow_call | Make the workflow reusable |
paths, branches, tags filters | Run only when relevant files or refs change |
Matrix Builds
yaml
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
python: ["3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "${{ matrix.python }}" }
- run: pip install -r requirements.txt && pytest
This creates 4 parallel jobs (2 operating systems times 2 Python versions).
Secrets, Variables and Contexts
yaml
env:
APP_ENV: staging # plain variable
steps:
- run: echo "Deploying to $APP_ENV from ${{ github.ref_name }} by ${{ github.actor }}"
- run: ./deploy.sh
env:
API_TOKEN: ${{ secrets.API_TOKEN }} # defined in Settings > Secrets and variables > Actions
REGION: ${{ vars.AWS_REGION }} # non-secret configuratio
Useful contexts: github.sha, github.ref_name, github.event_name, github.run_number, runner.os, secrets.*, vars.*, needs.<job>.outputs.*.
Caching and Artifacts
yaml
- uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ hashFiles('package-lock.json') }}
restore-keys: npm-
- run: npm ci && npm run build
- uses: actions/upload-artifact@v4
with:
name: dist
path: dist/
retention-days: 7
Build and Push a Docker Image
yaml
ame: Build image
on:
push:
branches: [main]
tags: ["v*"]
permissions:
contents: read
packages: write
jobs:
image:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=sha
type=semver,pattern={{version}}
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
cache-from: type=gha
cache-to: type=gha,mode=max
Jobs Depending on Each Other, Outputs and Environments
yaml
jobs:
build:
runs-on: ubuntu-latest
outputs:
tag: ${{ steps.vars.outputs.tag }}
steps:
- uses: actions/checkout@v4
- id: vars
run: echo "tag=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
deploy-staging:
needs: build
runs-on: ubuntu-latest
environment: staging
steps:
- run: echo "Deploy ${{ needs.build.outputs.tag }} to staging"
deploy-prod:
needs: deploy-staging
runs-on: ubuntu-latest
environment: production # configure required reviewers in Settings > Environments
steps:
- run: echo "Deploy to production after approval"
Environments let you attach secrets, protection rules and required reviewers to staging and production.
Passwordless Cloud Access with OIDC
Instead of storing long-lived cloud keys as secrets, the workflow requests a short-lived token from GitHub and exchanges it for cloud credentials. Example for AWS (create an IAM role that trusts GitHub's OIDC provider and limits the repository and branch):
yaml
permissions:
id-token: write # needed to request the OIDC token
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-deploy
aws-region: us-east-1
- run: aws sts get-caller-identity
- run: aws s3 sync ./site s3://my-site-bucket --delete
yaml
# Azure equivalent
- uses: azure/login@v2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
Reusable Workflows and Composite Actions
yaml
# .github/workflows/deploy.yml (reusable)
on:
workflow_call:
inputs:
environment: { type: string, required: true }
secrets:
token: { required: true }
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }}
steps:
- run: echo "Deploying to ${{ inputs.environment }}"
# caller workflow
jobs:
prod:
uses: myorg/platform/.github/workflows/deploy.yml@main
with: { environment: production }
secrets: { token: ${{ secrets.DEPLOY_TOKEN }} }
yaml
# .github/actions/setup-tools/action.yml (composite action)
name: Setup tools
runs:
using: composite
steps:
- run: sudo apt-get update && sudo apt-get install -y jq
shell: bash
Security Checklist for Workflows
- Set minimal
permissions: (default to contents: read)
- Do not run untrusted code from forked pull requests with secrets. Be careful with
pull_request_target
- Pin third-party actions to commit SHAs, and use Dependabot to update them
- Never print secrets. Use OIDC instead of static cloud keys
- Treat
${{ github.event.* }} text (titles, branch names) as untrusted input. Pass through env: instead of inlining into scripts
- Use environments with reviewers for production, and branch protection on
main
- Self-hosted runners: use ephemeral runners and never attach them to public repositories
Self-Hosted Runners
Run jobs on your own machines for special hardware, private networks or lower cost. Prefer ephemeral runners (one job, then destroyed), for example with Actions Runner Controller on Kubernetes.
Useful Built-in Features
concurrency: group to cancel older runs: concurrency: { group: ci-${{ github.ref }}, cancel-in-progress: true }
if: conditions, for example if: github.ref == 'refs/heads/main'
timeout-minutes: on jobs to avoid stuck runs
- Job summaries: write Markdown to
$GITHUB_STEP_SUMMARY
gh workflow run and gh run watch from the command line
Practice Tasks
- Create a CI workflow for a sample app with lint and unit tests
- Add a matrix for two language versions and a cache
- Build and push an image to GHCR with a SHA tag
- Add an environment
production that needs approval
- Replace a stored cloud access key with OIDC
Conclusion
GitHub Actions runs YAML workflows on GitHub-hosted or self-hosted runners. Use matrix builds, caching, environments with approvals, OIDC for cloud access, and reusable workflows, and keep permissions minimal.
Quick Summary: workflow = events + jobs + steps; matrix; cache; environments; OIDC; reusable workflows; least permissions.