GitHub Actions Fundamentals

What is GitHub Actions?

GitHub Actions is a continuous integration and continuous deployment (CI/CD) platform built directly into GitHub repositories. It automates software workflows, including building, testing, and deploying code whenever specific events occur in a repository.

GitHub Actions eliminates the need for external CI/CD tools by providing automation directly where code lives.

Core Concepts

Workflow

A YAML file in the .github/workflows/ directory that defines an automated process. Workflows specify when to run, what jobs to execute, and the steps within each job.

Event

A trigger that starts a workflow. Events include pushes, pull requests, scheduled times, manual triggers, or external webhooks.

Job

A collection of steps executed on the same runner (virtual machine). Jobs run in parallel by default but can be configured to run sequentially with dependencies.

Step

Individual tasks within a job. A step can run commands, execute scripts, or invoke actions (reusable units of code).

Runner

A virtual machine (GitHub-hosted or self-hosted) that executes workflow jobs. GitHub provides Ubuntu Linux, Windows, and macOS runners.

Action

A reusable unit of code packaged for GitHub Actions. Actions can be from the GitHub Marketplace, community repositories, or custom-built.

Workflow Structure

graph LR
    A["Event Trigger
(push, PR, schedule)"] -->B["Workflow"]
    B -->C["Job 1
Build"]
    B -->D["Job 2
Test"]
    B -->E["Job 3
Deploy"]
    C -->F["Step 1: Checkout"]
    C -->G["Step 2: Install"]
    C -->H["Step 3: Build"]
    
    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#e8f5e9

Simple Workflow Example

This workflow runs tests when code is pushed to the main branch.

# .github/workflows/test.yml
name: Run Tests

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm install
      
      - name: Run tests
        run: npm test

Explanation:

• on: defines triggers (push and pull_request events)
• jobs: defines the test job
• runs-on: specifies the runner OS
• steps: lists sequential tasks using uses: (actions) and run: (commands)

Common Event Triggers

Push Events

on:
  push:
    branches:
      - main
      - develop
    paths:
      - 'src/**'

Triggers when commits are pushed to specified branches and paths.

Pull Request Events

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened

Triggers when pull requests are opened, updated, or reopened.

Scheduled Events (Cron)

on:
  schedule:
    - cron: '0 2 * * *'  # Runs at 2 AM UTC daily

Manual Workflow Dispatch

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'

Enables manual workflow runs from the GitHub UI with input parameters.

Workflow Execution Flow

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub Repository
    participant Runner as GitHub Runner
    participant Action as Actions/Checks
    
    Dev->>GH: Push commit
    GH->>Runner: Trigger workflow
    Runner->>Runner: Checkout code
    Runner->>Runner: Set up environment
    Runner->>Runner: Run commands
    Runner->>Action: Report status
    Action->>GH: Update commit status
    GH->>Dev: Notification (pass/fail)

Real-World Example: Build and Deploy Node.js App

name: Build and Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run linter
        run: npm run lint
      
      - name: Run tests
        run: npm test
      
      - name: Build application
        run: npm run build
      
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    
    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: build-output
      
      - name: Deploy to production
        run: |
          echo "Deploying application..."
          # Add deployment commands here

Key features:

• Build and deploy jobs run sequentially (deploy depends on build)
• Artifacts pass build outputs between jobs
• npm ci ensures reproducible builds

Using Actions from the Marketplace

The GitHub Marketplace offers thousands of pre-built actions.

steps:
  # Checkout code
  - uses: actions/checkout@v4
  
  # Set up Python
  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'
  
  # Set up Docker
  - uses: docker/setup-buildx-action@v3
  
  # Send Slack notification
  - uses: slackapi/slack-github-action@v1.25.0
    with:
      payload: '{"text":"Build completed!"}'

Environment Variables and Contexts

Setting Environment Variables

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NODE_ENV: production
      API_URL: https://api.example.com
    
    steps:
      - name: Print environment
        run: echo "Environment is $NODE_ENV"

Using GitHub Contexts

steps:
  - name: Print context information
    run: |
      echo "Repository: ${{ github.repository }}"
      echo "Branch: ${{ github.ref }}"
      echo "Commit SHA: ${{ github.sha }}"
      echo "Actor: ${{ github.actor }}"

Common Workflow Patterns

Run on Multiple Operating Systems

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Conditional Execution

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main'
    run: echo "Deploying to production"
  
  - name: Deploy to staging
    if: github.ref == 'refs/heads/develop'
    run: echo "Deploying to staging"

Workflow Status Badges

Display workflow status in README files:

![Build Status](https://github.com/username/repo/workflows/Test/badge.svg)

Common Commands and Syntax

Debugging Workflows

Enable Debug Logging

Set repository secrets:

• ACTIONS_RUNNER_DEBUG: true
• ACTIONS_STEP_DEBUG: true

View Logs in GitHub UI

Navigate to Actions tab > Select workflow run > Click on job > Expand steps to view detailed logs.

Test Locally with act

# Install act (https://github.com/nektos/act)
act push

# Run specific job
act -j test

# Use different runner
act -P ubuntu-latest=node:16

Key Takeaways

• GitHub Actions automates workflows directly within GitHub repositories
• Workflows are YAML files triggered by events like pushes, pull requests, or schedules
• Jobs contain steps that run commands or invoke reusable actions
• Runners (GitHub-hosted or self-hosted) execute workflows on Ubuntu, Windows, or macOS
• Actions from the GitHub Marketplace provide pre-built functionality
• Environment variables and GitHub contexts pass data between steps
• Matrix strategies enable testing across multiple environments simultaneously
• Conditional execution controls when specific steps run based on branch or context

Next Steps: Create a .github/workflows/ directory and add a basic workflow to automate testing or deployment.