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	Usage	Example
push	Code pushed to branches	on: push
pull_request	PR opened/updated	on: pull_request
workflow_dispatch	Manual trigger	on: workflow_dispatch
schedule	Cron schedule	on: schedule
release	Release created	on: release
issues	Issue activity	on: issues

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

Context	Description	Example
github	Workflow info	${{ github.ref }}
env	Environment variables	${{ env.NODE_ENV }}
secrets	Repository secrets	${{ secrets.API_KEY }}
matrix	Matrix values	${{ matrix.node-version }}
steps	Step outputs	${{ steps.build.outputs.version }}
runner	Runner environment	${{ runner.os }}

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

Issue	Solution
Checkout fails	Use actions/checkout@v4
Secrets not available	Check secret name and scope
Step skipped	Check if conditions
Action version error	Update to latest version tag
Permission denied	Check permissions in workflow

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