GitHub Actions

Quick Start

Create a workflow file at .github/workflows/<name>.yml:

name: CI
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello World"

Essential concepts:

• •Workflow: Automated process defined in YAML, runs in response to events
• •Job: Set of steps that run on the same runner
• •Step: Individual action or shell command
• •Action: Reusable unit of code (GitHub marketplace or custom)
• •Event: What triggers the workflow (push, pull_request, schedule, etc.)

Common Workflow Patterns

Continuous Integration (CI)

• •Testing: Run tests on every push/PR
• •Linting: Code quality checks
• •Building: Compile code, build artifacts
• •See: references/tutorials/build-and-test-code/

Continuous Deployment (CD)

• •Deploy to production: Merge to main → deploy
• •Multi-environment: dev/staging/prod with approvals
• •Blue-green deployment: Zero-downtime deployments
• •See: references/how-tos/deploy/

Scheduled Tasks

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

Matrix Builds

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [14, 16, 18]

Workflow Syntax Reference

Required Structure

• •name: Workflow name
• •on: Triggers (events, schedules, manual)
• •jobs: One or more jobs

Key Job Fields

• •runs-on: Runner type (ubuntu-latest, windows-latest, macos-latest, self-hosted)
• •steps: Sequential list of steps
• •strategy: Matrix, fail-fast, max-parallel
• •outputs: Job-to-job data passing

Key Step Types

steps:
  - name: 'Checkout code'
    uses: actions/checkout@v4

  - name: 'Run script'
    run: npm test

  - name: 'Use action'
    uses: actions/setup-node@v4
    with:
      node-version: '18'

Complete syntax reference: references/reference/workflows-and-actions/workflow-syntax.md

Trigger Events

Common Events

• •push: Commits pushed to branch
• •pull_request: PR opened/updated/closed
• •workflow_dispatch: Manual trigger
• •schedule: Cron-based execution

Advanced Events

• •release: Release published
• •workflow_call: Reusable workflow
• •repository_dispatch: Webhook-triggered
• •environment: Environment deployment

Complete events reference: references/reference/workflows-and-actions/events-that-trigger-workflows.md

Expressions and Contexts

Expression Syntax

if: github.event_name == 'push'
runs-on: ${{ matrix.os }}

Common Contexts

• •github: Event details, repo, actor, ref
• •env: Environment variables
• •job: Job status, outputs
• •steps: Step outputs
• •runner: Runner OS, architecture
• •secrets: Encrypted secrets
• •vars: Custom variables

Complete expressions reference: references/reference/workflows-and-actions/expressions.md Complete contexts reference: references/reference/workflows-and-actions/contexts.md

Security Best Practices

Secrets Management

steps:
  - run: deploy.sh ${{ secrets.API_KEY }}

• •Never log secrets (GitHub auto-redacts)
• •Use secrets context for sensitive data
• •Store in repository Settings → Secrets

Security guide: references/concepts/security/secrets.md

GITHUB_TOKEN

• •Automatically provided authentication
• •Scoped permissions for repo access
• •Use for repo operations (clone, push, create PR)

GITHUB_TOKEN reference: references/concepts/security/github_token.md

OIDC (OpenID Connect)

• •Cloud deployments without long-lived credentials
• •Supports AWS, Azure, GCP, and more
• •Configure OIDC in workflow and cloud provider

OIDC guide: references/concepts/security/openid-connect.md

Security Hardening

• •Pin action versions (@v4 not @main)
• •Require approval for external workflows
• •Use artifact attestations for supply chain security

Security hardening: references/how-tos/security-harden-workflows/

Reusable Workflows and Actions

Reusable Workflows

# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      version:
        required: true
        type: string

# Call from another workflow
jobs:
  call:
    uses: org/repo/.github/workflows/reusable.yml@main
    with:
      version: '1.0'

Composite Actions

Combine multiple steps into a reusable action.

Custom Actions

• •JavaScript/TypeScript actions
• •Docker actions
• •Composite actions

Reusable workflows: references/concepts/workflows-and-actions/reusing-workflow-configurations.md Custom actions: references/concepts/workflows-and-actions/custom-actions.md

Deployment Patterns

Environments

jobs:
  deploy:
    environment: production
    environment:
      url: https://example.com

Deployment Protection Rules

• •Require approval before production
• •Restrict who can deploy
• •Wait timers for manual review

Third-Platform Deployments

• •Azure: App Service, Kubernetes, Static Web Apps
• •AWS: ECS, EKS, Lambda
• •GCP: Kubernetes Engine, Cloud Run

Deployment guides: references/how-tos/deploy/

Caching Dependencies

- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Caching reference: references/concepts/workflows-and-actions/dependency-caching.md

Artifacts and Logs

Upload Artifacts

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

Download Artifacts

- uses: actions/download-artifact@v4
  with:
    name: build-output

Artifacts reference: references/concepts/workflows-and-actions/workflow-artifacts.md

Troubleshooting

Enable Debug Logging

Add secret ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG to repository.

Common Issues

• •Permission errors: Check permissions scope
• •Path issues: Use ${{ github.workspace }}
• •Secret issues: Verify secret names and scopes

Viewing Logs

• •Actions tab → Workflow run → Job → Step
• •Download logs for offline analysis

Troubleshooting guide: references/how-tos/troubleshoot-workflows.md

Migrating from Other CI Systems

• •Jenkins: Import tool and manual patterns
• •GitLab CI: Syntax differences and equivalents
• •CircleCI: Migration patterns
• •Travis CI: Direct equivalents

Migration guides: references/tutorials/migrate-to-github-actions/

Language-Specific Guides

• •Node.js: references/tutorials/build-and-test-code/nodejs.md
• •Python: references/tutorials/build-and-test-code/python.md
• •Java: Maven, Gradle, Ant guides
• •.NET: Build and test patterns
• •Go, Rust, Ruby, PowerShell: Specific guides

Runners

GitHub-Hosted Runners

• •ubuntu-latest: Linux (Ubuntu)
• •windows-latest: Windows Server
• •macos-latest: macOS
• •Larger runners: More CPU/memory (paid)

Self-Hosted Runners

• •Custom environments
• •Private network access
• •Custom tools and dependencies

Runners reference: references/concepts/runners/

Complete Documentation Index

All 242 documentation files are available in references/:

Getting Started

• •Quickstart: references/get-started/quickstart.md
• •Understanding Actions: references/get-started/understand-github-actions.md
• •CI/CD overview: references/get-started/continuous-*.md

Concepts

• •Workflows: references/concepts/workflows-and-actions/
• •Runners: references/concepts/runners/
• •Security: references/concepts/security/

How-To Guides

• •Write workflows: references/how-tos/write-workflows/
• •Deploy: references/how-tos/deploy/
• •Create actions: references/how-tos/create-and-publish-actions/
• •Security hardening: references/how-tos/security-harden-workflows/

Reference

• •Workflow syntax: references/reference/workflows-and-actions/workflow-syntax.md
• •Events: references/reference/workflows-and-actions/events-that-trigger-workflows.md
• •Expressions: references/reference/workflows-and-actions/expressions.md
• •Contexts: references/reference/workflows-and-actions/contexts.md
• •Variables: references/reference/workflows-and-actions/variables.md
• •Workflow commands: references/reference/workflows-and-actions/workflow-commands.md

Tutorials

• •Build and test: references/tutorials/build-and-test-code/
• •Migrate to Actions: references/tutorials/migrate-to-github-actions/
• •Create actions: references/tutorials/create-actions/
• •Publish packages: references/tutorials/publish-packages/

Complete index: references/_index.md

Online Documentation

All documentation files include source URLs linking to the official GitHub Docs. Use these links to:

• •Verify information is current
• •Check for updates and changes
• •View rendered examples and screenshots
• •Report issues or suggest improvements

Official GitHub Actions Docs: https://docs.github.com/en/actions