Github Actions

GitHub Actions Workflow Creation

Create and configure GitHub Actions workflows for CI/CD, automation, testing, and deployment.

What GitHub Actions Provides

GitHub Actions is a CI/CD platform that automates build, test, and deployment pipelines through configurable workflows triggered by repository events.

Core capabilities:

• Continuous integration and deployment
• Automated testing on pull requests
• Package publishing and releases
• Issue and project management automation
• Scheduled tasks and cron jobs
• Multi-platform builds (Linux, Windows, macOS)

Key concepts:

• Workflows - Automated processes defined in YAML files
• Events - Triggers like push, pull_request, schedule
• Jobs - Sets of steps running on the same runner
• Steps - Individual tasks (scripts or actions)
• Actions - Reusable units of code
• Runners - Servers executing workflows

Creating a Workflow

Basic Workflow Structure

Workflows live in .github/workflows/ and use YAML syntax:

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Run tests
      run: npm test

Workflow File Location

Create workflow files at:

.github/workflows/workflow-name.yml

Each repository can have multiple workflows for different purposes.

Essential Components

1. Workflow name:

name: CI Pipeline

2. Event triggers:

on:
  push:
    branches: [ main, develop ]
  pull_request:
  workflow_dispatch:  # Manual trigger

3. Jobs definition:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

4. Steps with actions or scripts:

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - run: npm install
  - run: npm test

Common Workflow Patterns

CI/CD for Node.js

name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [18, 20, 22]
    
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm test

Build and Deploy

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Build
      run: npm run build
    
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

Multi-Job Workflow

name: Build and Test

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

Event Triggers

Common Events

Event Configuration

Branch filters:

on:
  push:
    branches:
      - main
      - 'releases/**'

Path filters:

on:
  push:
    paths:
      - 'src/**'
      - '**.js'

Schedule (cron):

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

Multiple events:

on:
  push:
    branches: [ main ]
  pull_request:
  workflow_dispatch:

Jobs and Steps

Job Configuration

Basic job:

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello"

Job dependencies:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
  
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: npm test

Conditional jobs:

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Matrix Builds

Run jobs with multiple configurations:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

Environment Variables

Repository secrets:

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.API_KEY }}
    run: ./deploy.sh

Environment variables:

env:
  NODE_ENV: production

jobs:
  build:
    env:
      BUILD_VERSION: 1.0.0
    steps:
      - run: echo $BUILD_VERSION

Using Actions

Finding Actions

Search GitHub Marketplace: https://github.com/marketplace?type=actions

Popular actions:

• actions/checkout@v4 - Clone repository
• actions/setup-node@v4 - Setup Node.js
• actions/setup-python@v5 - Setup Python
• actions/cache@v4 - Cache dependencies
• actions/upload-artifact@v4 - Store build artifacts
• actions/download-artifact@v4 - Retrieve artifacts

Action Usage

With inputs:

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

With outputs:

- id: build
  run: echo "version=1.0.0" >> $GITHUB_OUTPUT

- run: echo "Built version ${{ steps.build.outputs.version }}"

Contexts and Expressions

Common Contexts

Expressions

Conditionals:

if: github.event_name == 'push' && github.ref == 'refs/heads/main'

Functions:

if: contains(github.event.pull_request.labels.*.name, 'deploy')
if: startsWith(github.ref, 'refs/tags/')
if: success() || failure()

Security Best Practices

Secrets Management

1. Store secrets in repository settings - Never commit secrets
2. Use environment secrets - For deployment environments
3. Scope secrets appropriately - Organization vs. repository level

steps:
  - name: Deploy
    env:
      API_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    run: ./deploy.sh

Pull Request Security

Limit fork permissions:

on:
  pull_request_target:  # Use for fork PRs
    types: [opened, synchronize]

Require approval for forks: Configure in repository settings → Actions → Fork pull request workflows

Token Permissions

Restrict GITHUB_TOKEN:

permissions:
  contents: read
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({...})

Debugging Workflows

Enable Debug Logging

Set repository secrets:

• ACTIONS_STEP_DEBUG: true - Step debugging
• ACTIONS_RUNNER_DEBUG: true - Runner debugging

View Logs

Access workflow run logs from:

1. Repository → Actions tab
2. Select workflow run
3. Click job name
4. Expand steps to view output

Common Issues

Workflow Creation Checklist

Use this checklist when creating workflows:

• File in .github/workflows/ with .yml or .yaml extension
• Workflow has descriptive name
• Appropriate event triggers configured
• Runner OS specified with runs-on
• First step uses actions/checkout@v4
• Secrets used for sensitive data (never hardcoded)
• Job dependencies configured with needs if required
• Matrix strategy used for multi-environment testing (if needed)
• Artifacts uploaded for build outputs (if needed)
• Appropriate permissions set for GITHUB_TOKEN
• Workflow tested on feature branch before merging

Additional Resources

Reference Files

For detailed syntax and patterns:

• references/workflow-syntax.md - Complete YAML syntax reference
• references/common-patterns.md - Workflow patterns by use case
• references/security-guide.md - Security best practices and OIDC

Example Workflows

Working examples in examples/:

• examples/ci-nodejs.yml - Node.js CI with testing and linting
• examples/ci-python.yml - Python CI with multiple versions
• examples/deploy-pages.yml - Deploy to GitHub Pages
• examples/release.yml - Automated releases with changelog
• examples/docker-build.yml - Build and push Docker images

External Resources

• GitHub Actions documentation: https://docs.github.com/en/actions
• GitHub Actions Marketplace: https://github.com/marketplace?type=actions
• Workflow syntax reference: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

Quick Reference

Minimal workflow:

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Common action versions:

• actions/checkout@v4
• actions/setup-node@v4
• actions/setup-python@v5
• actions/cache@v4
• actions/upload-artifact@v4

Useful expressions:

• ${{ github.ref }} - Current branch/tag
• ${{ github.sha }} - Commit SHA
• ${{ runner.os }} - Runner OS (Linux, Windows, macOS)
• ${{ secrets.SECRET_NAME }} - Access secret
• ${{ matrix.value }} - Matrix value