GitHub Actions Tutorial: Workflows, Matrix Builds, OIDC, Docker and Reusable Workflows

DevOps Certification 26 min min read Updated: Nov 17, 2026 Intermediate
GitHub Actions Tutorial: Workflows, Matrix Builds, OIDC, Docker and Reusable Workflows
Intermediate Topic 3 of 4

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

EventUse
push, pull_requestCI on code changes
workflow_dispatchManual run with optional inputs
schedule (cron)Nightly jobs, dependency checks
releasePublish on a new release
workflow_callMake the workflow reusable
paths, branches, tags filtersRun 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

  1. Create a CI workflow for a sample app with lint and unit tests
  2. Add a matrix for two language versions and a cache
  3. Build and push an image to GHCR with a SHA tag
  4. Add an environment production that needs approval
  5. 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.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators