Skip to main content

GitHub Actions Beginner Guide

What is GitHub Actions?

GitHub Actions is a CI/CD (Continuous Integration/Continuous Deployment) tool built into GitHub. It allows you to automate workflows, such as building, testing, and deploying your code.

Key Concepts

1. Workflow​

  • A YAML file that defines the automation process.
  • Location: .github/workflows/<workflow-name>.yml
  • Triggered by events like push, pull_request, or manually using workflow_dispatch.

Example:

name: CI Workflow
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

2. Jobs​

  • A workflow is composed of one or more jobs.
  • Each job runs on a separate virtual machine.
  • Jobs can run in parallel or sequentially using needs.

Example:

jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - name: Step 1
        run: echo "Job 1"
  job2:
    needs: job1  # Run after job1
    runs-on: ubuntu-latest
    steps:
      - name: Step 2
        run: echo "Job 2"

3. Steps​

  • A sequence of commands or actions executed in a job.
  • Steps can include:
    • Shell commands (run).
    • Pre-built actions (uses).

Example:

steps:
  - name: Run a command
    run: echo "Hello, World!"
  - name: Use an action
    uses: actions/checkout@v4

4. Triggers​

  • Define when the workflow runs.
  • Common triggers:
    • push – When changes are pushed to a branch.
    • pull_request – When a pull request is opened or updated.
    • schedule – Runs on a schedule using cron syntax.
    • workflow_dispatch – Allows manual triggering.

Example:

on:
  push:
    branches:
      - main
  pull_request:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

5. Runners​

  • The environment where jobs are executed.
  • Types:
    • Hosted runners: GitHub-provided (Ubuntu, Windows, macOS).
    • Self-hosted runners: Custom environments.

Key Features for Beginners

1. Reusable Actions​

Pre-defined actions shared on the GitHub Marketplace.

Example:

steps:
  - uses: actions/checkout@v4

2. Environment Variables​

  • Use env or predefined variables (e.g., ${{ github.event }}).

Example:

env:
  NODE_ENV: production
steps:
  - name: Print environment
    run: echo $NODE_ENV

3. Secrets​

  • Securely store sensitive data like API keys.
  • Access via ${{ secrets.<name> }}.

Example:

steps:
  - name: Use secret
    run: echo ${{ secrets.MY_SECRET }}

4. Artifacts​

  • Save files during a workflow for later use.
  • Upload with actions/upload-artifact@v3.

Example:

steps:
  - name: Upload artifact
    uses: actions/upload-artifact@v3
    with:
      name: build-output
      path: ./build

5. Matrix Builds​

  • Test your code on multiple environments or configurations.

Example:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.7, 3.8, 3.9]
    steps:
      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      - name: Run tests
        run: python -m unittest

Typical Workflow Example

name: Build and Test Workflow

on:
  push:
    branches:
      - main

jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.9

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest

      - name: Run tests
        run: pytest

Benefits of GitHub Actions

  1. Easy Integration: Built directly into GitHub.
  2. Automation: Automates repetitive tasks like testing and deployment.
  3. Flexibility: Highly configurable with custom workflows.
  4. Scalability: Supports parallel and matrix jobs.

Helpful Tips for Beginners

  1. Start Small: Begin with simple workflows like running a script.
  2. Use Pre-built Actions: Explore the GitHub Marketplace.
  3. Debugging: Enable debug logging with ACTIONS_STEP_DEBUG=true.
  4. Learn from Examples: Refer to GitHub’s Actions documentation.

This document provides a beginner-friendly introduction to GitHub Actions. Let me know if you’d like to add more examples or topics!