GitHub Actions FAQ & Answers

Debug workflows with multiple techniques:

Enable debug logging:

• Set repository secrets: ACTIONS_STEP_DEBUG=true, ACTIONS_RUNNER_DEBUG=true
• Re-run workflow to see detailed logs

Interactive debugging:

- uses: mxschmitt/action-tmate@v3  # SSH access to runner
  if: failure()  # Only on failure

Local testing:

# Install act (https://github.com/nektos/act)
act -j build  # Test 'build' job locally
act -l  # List available jobs

Variable inspection:

- name: Debug context
  run: |
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"
    echo "Context: ${{ toJSON(github) }}"

Use workflow_dispatch for manual triggers. Download diagnostic logs from UI. Warning: debug logs expose secrets.

GitHub Actions is GitHub's native CI/CD platform that automates build, test, and deployment workflows directly within your repository. Workflows are defined as YAML files in .github/workflows/ and are triggered by events like code pushes, pull requests, or scheduled runs. Key components include workflows (automated processes), jobs (sets of steps that run on runners), steps (individual tasks), and actions (reusable units). Benefits include seamless GitHub integration, free tier for public repositories, access to thousands of marketplace actions, matrix builds, caching, artifacts, and built-in secrets management. Perfect for testing, deployment automation, and custom workflows without leaving GitHub.

Display workflow status badges in README for quick build health visibility:

Basic badge (main branch):

![CI](https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg)

Branch-specific badge:

![CI](https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg?branch=develop)

Linked badge (clickable):

[![CI](https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/owner/repo/actions/workflows/ci.yml)

Multiple workflow badges:

![Build](https://github.com/owner/repo/actions/workflows/build.yml/badge.svg)
![Tests](https://github.com/owner/repo/actions/workflows/test.yml/badge.svg)
![Deploy](https://github.com/owner/repo/actions/workflows/deploy.yml/badge.svg)

Status colors: green (passing), red (failing), yellow (no status). Updates automatically. Perfect for open source projects and team dashboards.

Download artifacts from previous jobs using actions/download-artifact@v4. Example:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: ./dist
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: ./dist
      - run: npm run deploy

Download all artifacts: omit name. v4 supports cross-repository downloads with GITHUB_TOKEN actions:read permission. Use needs: for job dependencies. Perfect for multi-stage CI/CD pipelines with build → test → deploy stages.

Control job and step execution with if: conditions using status functions and context:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy (main branch only)
        if: github.ref == 'refs/heads/main'
        run: npm run deploy
      
      - name: Cleanup (always run)
        if: always()
        run: ./cleanup.sh
  
  notify:
    needs: build
    if: failure()  # Run only if build fails
    runs-on: ubuntu-latest
    steps:
      - name: Send failure notification
        run: curl -X POST ${{ secrets.SLACK_WEBHOOK }}

Status functions: success() (default), failure(), always(), cancelled(). String functions: contains(), startsWith(), endsWith(). Operators: ==, !=, &&, ||, !. Perfect for conditional deployments, notifications, and cleanup.

Configure pull request triggers to run workflows when PRs are opened, updated, or closed. Example:

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main, develop]
    paths:
      - 'src/**'
      - '!docs/**'

Activity types include: opened, synchronize (new commits), reopened, closed, assigned, review_requested. Access PR context: github.event.pull_request.number, github.event.pull_request.head.ref, github.event.pull_request.base.ref. Security: forked PRs use pull_request_target for write access but run untrusted code in isolated context. Set read-only GITHUB_TOKEN permissions by default. Perfect for automated testing, code quality checks, and security scanning before merge.

Use OpenID Connect (OIDC) for keyless authentication, eliminating long-lived secrets. Configure trust between GitHub (https://token.actions.githubusercontent.com) and your cloud provider.

AWS (IAM Role):

- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::123456789012:role/github-actions
    aws-region: us-west-2

Azure (Workload Identity):

- uses: azure/login@v2
  with:
    client-id: ${{ secrets.AZURE_CLIENT_ID }}
    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

GCP (Workload Identity Federation):

- uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: 'projects/123/locations/global/workloadIdentityPools/github/providers/github'
    service_account: '[email protected]'

Tokens auto-expire (1 hour), scoped to repo/branch. No secret rotation needed. Industry standard for 2025 cloud deployments.

Configure push triggers in your workflow YAML to run on code pushes. Use on: push with optional branch and path filters. Example:

on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**'
      - '!docs/**'
    tags:
      - 'v*'

Branch filters trigger on specific branches, path filters run only when matching files change, and tag filters trigger on version tags. Use paths-ignore to exclude files. Push events provide context: github.ref, github.sha, github.event.head_commit.message, and github.actor. Combine with concurrency controls to prevent duplicate runs. Perfect for CI on code changes, automated releases, and version tagging workflows.

Cache Docker layers with BuildKit for faster containerized builds. Use docker/build-push-action@v5 with cache configuration:

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v5
  with:
    context: .
    push: false
    cache-from: type=gha
    cache-to: type=gha,mode=max

GitHub Actions cache (type=gha) is optimized for CI/CD. For local cache:

- uses: actions/cache@v4
  with:
    path: /tmp/.buildx-cache
    key: ${{ runner.os }}-buildx-${{ hashFiles('**/Dockerfile') }}

For build artifacts (Maven, Gradle, Cargo): cache ~/.m2, ~/.gradle, target/. Reduces build time by 60-80%. Cache limit: 10GB per repository.

Reusable workflows eliminate duplication by calling workflows from other workflows. Define reusable workflow:

# .github/workflows/reusable-deploy.yml
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      API_KEY:
        required: true

Call reusable workflow:

jobs:
  deploy:
    uses: ./.github/workflows/reusable-deploy.yml@main
    with:
      environment: production
    secrets:
      API_KEY: ${{ secrets.PROD_API_KEY }}

Max nesting: 4 levels (2025). Can call from matrix. Use for CI patterns, security scans, deployment procedures. Centralized updates benefit entire organization. Essential for enterprise consistency.

Matrix strategy runs jobs with multiple variable combinations for comprehensive testing:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false  # Continue other jobs on failure
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20, 22]
        include:
          - os: ubuntu-latest
            node-version: 20
            experimental: true
        exclude:
          - os: macos-latest
            node-version: 18
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm test

Max 256 jobs per matrix. Use include for additional configs, exclude to skip combinations. Perfect for cross-platform testing and multi-version support.

Usage Limits & Pricing (2025):

Free tier:

• Public repos: Unlimited minutes
• Private repos: 2,000 min/month (Free), 3,000 min/month (Pro)
• Storage: 500MB artifacts

Minute costs:

• Linux: $0.008/min (1x multiplier)
• Windows: $0.016/min (2x multiplier)
• macOS: $0.08/min (10x multiplier)

Monitoring:

# Settings > Billing > Actions minutes
# Insights > Actions > Workflow runs

Cost optimization:

• Use Linux runners (cheapest)
• Enable concurrency: cancel-in-progress: true (saves duplicate runs)
• Cache dependencies (actions/cache@v4)
• Set timeout-minutes: 30 to prevent runaway jobs
• Exclude unnecessary matrix combinations
• Self-hosted runners for high-volume (>10K min/month)

Retention: Workflows 90 days, artifacts 90 days (configurable 1-400 days).

GitHub-hosted runners:

• Pre-configured: ubuntu-latest (22.04), windows-latest (2022), macos-latest (14)
• Free: 2,000 min/month (public), 3,000 min/month (Pro)
• Clean state per job, automatic updates
• Cost: $0.008/min (Linux), $0.016/min (Windows), $0.08/min (macOS)

Self-hosted runners:

runs-on: [self-hosted, linux, x64, gpu]

• Unlimited minutes, custom hardware (GPU, ARM), persistent cache
• Security: runs in your network, access to internal resources
• Setup: ./config.sh --url https://github.com/org/repo --token TOKEN
• Use for: GPU workloads, cost optimization at scale (>10K min/month), compliance, internal resources

Security risk: Don't use self-hosted runners on public repos (untrusted code execution). Use GitHub-hosted or isolated runners.

Set environment variables at multiple scopes:

env:
  NODE_ENV: production  # Workflow-level (all jobs)

jobs:
  build:
    env:
      ARTIFACT_NAME: my-app  # Job-level (all steps)
    steps:
      - name: Build
        env:
          DATABASE_URL: ${{ secrets.DB_URL }}  # Step-level
        run: npm run build
      
      - name: Set runtime env
        run: echo "BUILD_TIME=$(date)" >> $GITHUB_ENV
      
      - name: Use runtime env
        run: echo "Built at $BUILD_TIME"

Access: ${{ env.VAR }} (YAML), $VAR (shell). Default vars: GITHUB_REF, GITHUB_SHA, GITHUB_ACTOR, GITHUB_REPOSITORY. Use $GITHUB_ENV for dynamic variables. Perfect for configuration management and data flow.

Create dependency graphs with needs: and pass data via job outputs:

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.get_version.outputs.version }}
    steps:
      - id: get_version
        run: echo "version=1.2.3" >> $GITHUB_OUTPUT
  
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Testing version ${{ needs.build.outputs.version }}"
  
  deploy:
    needs: [build, test]
    if: needs.build.result == 'success'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh ${{ needs.build.outputs.version }}

Use needs: for execution order. Output with $GITHUB_OUTPUT (not deprecated set-output). Check needs.<job>.result for conditional execution. Perfect for build → test → deploy pipelines.

Store sensitive credentials in GitHub repository secrets (Settings > Secrets and variables > Actions). Access in workflows:

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.API_KEY }}
      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
    run: |
      curl -H "Authorization: Bearer ${{ secrets.API_KEY }}" \
        https://api.example.com/deploy

Secrets are encrypted at rest (AES-256-GCM) and masked in logs. Best practices: prefer OIDC over long-lived secrets, use environment secrets for production, rotate regularly, never echo/log secrets. Organization secrets can be shared across repositories. Use ::add-mask:: to mask dynamic values. Essential for API keys, database credentials, and deployment tokens.

2025 Security Best Practices:

1. Minimal GITHUB_TOKEN permissions (critical):

permissions:
  contents: read  # Default read-only
jobs:
  deploy:
    permissions:
      contents: write  # Job-specific escalation

Set org-wide default: Settings > Actions > Workflow permissions > Read repository contents

2. Pin actions to SHA (supply chain security):

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

3. OIDC over secrets:

• Prefer workload identity federation for cloud deployments

4. Environment protection:

• Required reviewers for production
• Deployment branch restrictions

5. Secret handling:

• Never echo ${{ secrets.API_KEY }}
• Use ::add-mask:: for dynamic secrets

6. Third-party action review:

• Check code, stars, maintainer reputation

Essential for preventing supply chain attacks and credential theft.

Environment secrets provide scoped credentials with deployment protection rules. Configure in Settings > Environments:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://prod.example.com
    steps:
      - name: Deploy
        env:
          API_KEY: ${{ secrets.PROD_API_KEY }}
        run: ./deploy.sh

Protection rules: required reviewers (1-6 people/teams), wait timer (0-43,200 min), deployment branches (main only). Environment secrets override repository secrets. Approval required before job accesses secrets. Wait timers prevent rapid deploys. Use for production deployments requiring oversight, compliance workflows, and progressive delivery. Audit log tracks all approvals.

Use expressions ${{ }} and contexts for dynamic workflows:

Common functions:

# String operations
if: contains(github.event.head_commit.message, '[skip-ci]')
if: startsWith(github.ref, 'refs/tags/')
if: endsWith(github.actor, '-bot')

# File hashing for cache keys
key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

# JSON operations
run: echo '${{ toJSON(github) }}'  # Debug context
matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}  # Dynamic matrix

Key contexts:

• github.* - Event data (ref, sha, actor, repository)
• env.* - Environment variables
• secrets.* - Repository/environment secrets
• steps.<id>.outputs.* - Step outputs
• needs.<job>.outputs.* - Job outputs
• matrix.* - Matrix variables
• runner.* - Runner info (os, arch, temp)

Operators: ==, !=, <, >, &&, ||, !. Use for conditional execution, dynamic names, and context-aware behavior.

Configure artifact retention to manage storage costs and compliance. Set during upload:

- uses: actions/upload-artifact@v4
  with:
    name: build
    path: dist/
    retention-days: 7  # 1-90 days (90 default)

Repository-level: Settings > Actions > Artifact and log retention (max 400 days for Enterprise). Programmatic cleanup with @actions/github-script:

await github.rest.actions.deleteArtifact({
  owner: context.repo.owner,
  repo: context.repo.repo,
  artifact_id: 123456
});

Monitor usage in Insights > Actions. Use short retention (7-14 days) for CI artifacts, longer (90 days) for releases. Essential for cost management at scale.

Environments provide deployment protection with approval gates. Configure in Settings > Environments:

Protection rules:

• Required reviewers: 1-6 people/teams must approve
• Wait timer: 0-43,200 minutes delay before deployment
• Deployment branches: Restrict to main/protected branches only

Workflow usage:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://prod.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          API_KEY: ${{ secrets.PROD_API_KEY }}
        run: ./deploy.sh

Workflow pauses until approved. Environment secrets override repository secrets. Deployment history tracked with timestamps and approvers. Essential for compliance, SOC 2, and governance requirements. Use for production, staging, and compliance-critical deployments.

Upload build outputs, test results, and deployment files using actions/upload-artifact@v4 (mandatory since Jan 2025, v3 deprecated). Example:

- uses: actions/upload-artifact@v4
  with:
    name: build-assets
    path: |
      dist/
      coverage/
    retention-days: 7
    compression-level: 6

v4 improvements: 90% faster uploads, immediate UI availability, cross-repository downloads with GITHUB_TOKEN. Note: cannot upload to same artifact name multiple times (breaking change from v3). Size limit: 10GB per artifact. Default retention: 90 days (max 1 year). Artifacts downloadable via UI, API, or actions/download-artifact@v4. Perfect for build outputs, test reports, and deployment packages.

Deploy to AWS using official actions with OIDC authentication (recommended 2025):

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: us-east-1
      - name: Deploy to S3
        run: aws s3 sync ./dist s3://my-bucket --delete
      - name: Deploy ECS
        uses: aws-actions/amazon-ecs-deploy-task-definition@v2
        with:
          task-definition: task-def.json
          service: my-service
          cluster: my-cluster

Prefer OIDC over access keys. Use least-privilege IAM policies. Perfect for S3, Lambda, ECS, and CloudFormation deployments.

Cache npm dependencies to accelerate builds and reduce network usage. Starting in 2024, actions/setup-node@v4 auto-enables caching when packageManager field exists in package.json:

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'  # Auto-caches based on package-lock.json
- run: npm ci

Manual caching with actions/cache@v4:

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

Cache limit: 10GB per repository. Reduces build time by 50-80%. Use npm ci (not npm install) for reproducible builds.

Create JavaScript actions for complex logic and API integrations:

action.yml:

name: 'Custom Action'
description: 'Process data and call APIs'
inputs:
  api-token:
    description: 'API token'
    required: true
outputs:
  result:
    description: 'Processing result'
runs:
  using: 'node20'
  main: 'dist/index.js'

index.js:

const core = require('@actions/core');
const github = require('@actions/github');

async function run() {
  try {
    const token = core.getInput('api-token');
    const octokit = github.getOctokit(token);
    
    // Your logic here
    const result = await processData();
    
    core.setOutput('result', result);
  } catch (error) {
    core.setFailed(error.message);
  }
}

run();

Bundle with @vercel/ncc to dist/. Use node20 runtime. Perfect for GitHub API interactions, data processing, and marketplace sharing.

GitHub Actions workflows follow a specific YAML structure with key components at the top level. Basic structure: name: Workflow Name for display, on: [push, pull_request] for triggers, jobs: containing one or more jobs. Each job needs runs-on: ubuntu-latest for runner specification and steps: for individual actions. Example structure: name: CI on: push jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node run: npm ci - name: Run tests run: npm test. Workflows stored in .github/workflows/ directory with .yml or .yaml extension. Multiple workflows per repository run in parallel by default. Understanding this structure is fundamental for creating effective CI/CD pipelines.

Deploy to Azure using official actions with OIDC workload identity (recommended 2025):

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - uses: azure/webapps-deploy@v3
        with:
          app-name: my-webapp
          package: ./dist
      - name: Deploy Container
        run: |
          az container create \
            --resource-group my-rg \
            --name my-app \
            --image myregistry.azurecr.io/myapp:latest

Use deployment slots for zero-downtime. Perfect for App Service, Functions, AKS, and Container Instances.

Deploy to GCP using workload identity federation (keyless, recommended 2025):

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: 'projects/123/locations/global/workloadIdentityPools/github/providers/github'
          service_account: '[email protected]'
      - uses: google-github-actions/deploy-cloudrun@v2
        with:
          service: my-service
          image: gcr.io/my-project/my-app:${{ github.sha }}
          region: us-central1
      - name: Deploy Function
        run: |
          gcloud functions deploy my-func \
            --runtime nodejs20 \
            --trigger-http

No service account keys needed. Perfect for Cloud Run, Functions, GKE, and App Engine.

Communicate with runner using environment files (recommended) and workflow commands:

Environment files (2025 standard):

# Set step outputs
echo "version=1.2.3" >> $GITHUB_OUTPUT

# Set environment variables
echo "BUILD_TIME=$(date)" >> $GITHUB_ENV

# Add to PATH
echo "$HOME/.local/bin" >> $GITHUB_PATH

Workflow commands (legacy but still useful):

# Mask sensitive values
echo "::add-mask::$SECRET_VALUE"

# Group logs
echo "::group::Installing dependencies"
npm install
echo "::endgroup::"

# Annotations
echo "::error file=app.js,line=42::Syntax error"
echo "::warning::Deprecated function used"
echo "::notice::Build completed"

Deprecated: set-output, set-env (security risk). Use $GITHUB_OUTPUT and $GITHUB_ENV instead.

GITHUB_TOKEN is automatically generated per workflow run for GitHub API authentication. Access via ${{ secrets.GITHUB_TOKEN }} or ${{ github.token }}. 2025 Best Practice: Set read-only by default (Settings > Actions > Workflow permissions):

permissions:
  contents: read  # Explicit minimal permissions

jobs:
  deploy:
    permissions:
      contents: write  # Job-level override
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Create Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh release create v1.0.0

Token auto-expires at job completion, scoped to repository. Default for orgs created before Feb 2023: read-write (security risk). Forked PRs: read-only automatically. Essential for secure GitHub API access without PATs.

Prevent concurrent runs and deployment race conditions with concurrency::

name: Deploy
on:
  push:
    branches: [main]

concurrency:
  group: production-deploy
  cancel-in-progress: false  # Don't cancel production deploys

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Per-branch concurrency:

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true  # Cancel old PR runs

Per-workflow concurrency:

concurrency: ${{ github.workflow }}-${{ github.ref }}

Use cancel-in-progress: true for CI (saves minutes), false for deployments (avoid partial deploys). Perfect for preventing deployment conflicts and saving runner minutes on PR updates.

Composite actions package multiple steps into reusable actions:

Create .github/actions/setup-node-app/action.yml:

name: 'Setup Node App'
description: 'Install Node and dependencies'
inputs:
  node-version:
    description: 'Node.js version'
    required: true
    default: '20'
outputs:
  cache-hit:
    description: 'Whether cache was hit'
    value: ${{ steps.cache.outputs.cache-hit }}
runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: 'npm'
    - run: npm ci
      shell: bash

Use in workflow:

- uses: ./.github/actions/setup-node-app
  with:
    node-version: 20

Note: Must specify shell: for run steps. Simpler than reusable workflows for step-level reuse.

Configure scheduled workflows using cron syntax for timed execution. Example:

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC
    - cron: '0 0 * * 0'  # Weekly on Sunday midnight
  workflow_dispatch:  # Enable manual triggering

Cron format: minute (0-59) hour (0-23) day (1-31) month (1-12) weekday (0-6). Always UTC timezone. Scheduled workflows run on default branch only with full secret access. Use workflow_dispatch for manual testing. Set timeout-minutes (recommended: 30) to prevent runaway jobs. Perfect for nightly builds, dependency updates with Dependabot, security scans, backup tasks, and automated reporting.