Chapter 4: Building CI/CD with GitHub Actions

Introduction to Continuous Integration & GitHub Actions

Welcome to Chapter 4! In our journey through DevOps, we’ve explored the foundational elements of Linux, command-line mastery, and the power of Git for version control. Now, it’s time to elevate our development process by introducing Continuous Integration (CI) and Continuous Delivery (CD).

CI/CD is the backbone of modern software development. It’s about automating the build, test, and deployment phases of your application lifecycle, ensuring that your code is always in a releasable state. Imagine pushing a change, and automatically, your tests run, your application builds, and it’s ready to be deployed – that’s the magic of CI/CD! This automation drastically reduces manual errors, speeds up development cycles, and allows teams to deliver value faster and more reliably.

In this chapter, we’ll focus on GitHub Actions, a powerful, flexible, and fully integrated CI/CD platform directly within GitHub. Having already mastered Git and GitHub in the previous chapter, GitHub Actions will feel like a natural extension, allowing you to automate virtually any aspect of your development workflow. We’ll start with the basics, build our first workflow, and understand the core components that make GitHub Actions so effective. Get ready to make your development process smarter, faster, and more robust!

Core Concepts: What are GitHub Actions?

GitHub Actions allow you to automate, customize, and execute your software development workflows directly in your repository. You can discover, create, and share actions to perform any job, including CI/CD, and combine actions to create a fully custom workflow.

Let’s break down the key components:

1. Workflows

Think of a workflow as a single, complete automated process. It’s defined by a YAML file (.yml or .yaml) that lives in the .github/workflows/ directory of your repository. Each repository can have multiple workflows, each designed for a specific purpose (e.g., one for building, one for testing, one for deploying).

2. Events

An event is a specific activity that triggers a workflow. Common events include:

• push: When code is pushed to a branch.
• pull_request: When a pull request is opened, synchronized, or reopened.
• schedule: To run a workflow at specific times (like a cron job).
• workflow_dispatch: To manually trigger a workflow from the GitHub UI or API.

3. Jobs

A job is a set of steps in a workflow that executes on the same runner. Workflows can have one or more jobs, and by default, jobs run in parallel. You can also configure jobs to run sequentially, where one job depends on the successful completion of a previous job.

4. Steps

A step is an individual task within a job. Steps can be:

• Executing a command (e.g., run: npm install).
• Running an action (e.g., uses: actions/checkout@v4).
• Running a script.

5. Actions

An action is a reusable piece of code that simplifies your workflow. Actions can be written by GitHub, the open-source community, or you can even write your own. The GitHub Marketplace offers thousands of actions for various tasks, from setting up specific programming languages to deploying to cloud providers. They save you from writing repetitive scripts.

6. Runners

A runner is a server that runs your workflow when it’s triggered. GitHub provides GitHub-hosted runners (virtual machines running Linux, Windows, or macOS) that are automatically managed and updated. You can also set up self-hosted runners on your own infrastructure for more control or specific hardware requirements. For our learning, GitHub-hosted runners are perfect.

Visualizing the Workflow

Let’s visualize how these components fit together:

Wait a moment, take a look at the diagram. Can you trace how an event like a push could lead to your code being built, tested, and potentially deployed? This flow is the core of CI/CD!

Step-by-Step Implementation: Our First GitHub Action

Let’s create a simple workflow that automatically checks out our code and runs a basic Python script whenever we push changes to our repository.

Prerequisites:

• A GitHub account.
• A repository on GitHub (you can create a new one or use one from Chapter 3).
• Git installed and configured locally.

Step 1: Create a Sample Python Project

First, let’s create a very simple Python project in your local repository.

1. Navigate to your local repository directory:

   cd my-devops-repo # Or whatever your repo name is
   

2. Create a simple Python file:

   echo 'print("Hello from GitHub Actions!")' > hello.py
   

3. Create a requirements.txt (even if it’s empty for now, it’s good practice):

   touch requirements.txt
   

4. Add and commit these files:

   git add hello.py requirements.txt
   git commit -m "Add sample Python script and requirements"
   git push origin main # Assuming 'main' is your default branch
   

   Great! Now your GitHub repository has a hello.py file.

Step 2: Create Your First Workflow File

GitHub Actions workflows are defined in YAML files inside a special directory.

1. Create the workflow directory:

   mkdir -p .github/workflows
   

   The -p flag ensures that intermediate directories are created if they don’t exist. GitHub automatically looks for workflow files in this specific path.

2. Create your workflow YAML file:

   touch .github/workflows/my-first-workflow.yml
   

   You can name your workflow file anything you want, but it’s good practice to give it a descriptive name.

3. Open my-first-workflow.yml in your favorite text editor.

Step 3: Build the Workflow Incrementally

Now, let’s add content to my-first-workflow.yml line by line, explaining each part.

Part A: Workflow Name and Trigger Event

# .github/workflows/my-first-workflow.yml
name: My First Python CI Workflow

on: [push]

• name: My First Python CI Workflow: This is a human-readable name for your workflow. It will appear in the GitHub Actions tab.
• on: [push]: This specifies when the workflow should run. Here, [push] means it will trigger every time someone pushes changes to any branch in the repository. We use square brackets because you can specify multiple events (e.g., on: [push, pull_request]).

Part B: Defining a Job

# .github/workflows/my-first-workflow.yml
name: My First Python CI Workflow

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

• jobs:: This keyword defines the jobs within your workflow.
• build:: This is the ID for our first job. You can name jobs anything descriptive (e.g., test, deploy).
• runs-on: ubuntu-latest: This tells GitHub which type of runner to use. ubuntu-latest is a GitHub-hosted runner running the latest Ubuntu Linux version (currently Ubuntu 22.04 LTS as of 2026-01-12). Other options include windows-latest or macos-latest.

Part C: Defining Steps within the Job

# .github/workflows/my-first-workflow.yml
name: My First Python CI Workflow

on: [push]

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

• steps:: This keyword lists all the individual steps that build job will execute. Each step begins with a hyphen (-).
• name: Checkout repository code: A descriptive name for this step, visible in the workflow logs.
• uses: actions/checkout@v4: This is our first action! The actions/checkout@v4 action is a standard GitHub Action that checks out your repository code into the runner’s workspace, making it available for subsequent steps. @v4 specifies the version of the action to use, which is good practice for stability.

Part D: Setting up Python and Running Our Script

# .github/workflows/my-first-workflow.yml
name: My First Python CI Workflow

on: [push]

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

      - name: Set up Python environment
        uses: actions/setup-python@v5
        with:
          python-version: '3.10' # Specify the Python version

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

      - name: Run our Python script
        run: python hello.py

• uses: actions/setup-python@v5: Another essential action! This one sets up a specific Python version on the runner. We’re using @v5, the latest stable version.
• with: python-version: '3.10': The with keyword allows you to pass inputs to an action. Here, we tell setup-python to configure Python 3.10. You could use '3.x' for the latest in the 3.x series, or even a list ['3.10', '3.11'] for testing across multiple versions.
• name: Install dependencies & run: pip install -r requirements.txt: This step installs any Python packages listed in requirements.txt. Even though ours is empty, it demonstrates a common CI pattern. The run keyword executes shell commands directly on the runner.
• name: Run our Python script & run: python hello.py: Finally, this step executes our hello.py script. We expect to see “Hello from GitHub Actions!” in the logs.

Your complete my-first-workflow.yml file should look like this:

# .github/workflows/my-first-workflow.yml
name: My First Python CI Workflow

on: [push]

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

      - name: Set up Python environment
        uses: actions/setup-python@v5
        with:
          python-version: '3.10' # Specify the Python version

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

      - name: Run our Python script
        run: python hello.py

Step 4: Commit and Push to Trigger the Workflow

Save your my-first-workflow.yml file. Now, add and commit this new file, then push it to GitHub:

git add .github/workflows/my-first-workflow.yml
git commit -m "Add first GitHub Actions workflow"
git push origin main

Step 5: Observe the Workflow Run

1. Go to your repository on GitHub.
2. Click on the “Actions” tab.
3. You should see your “Add first GitHub Actions workflow” commit message, and next to it, a yellow dot indicating the workflow is running.
4. Click on the workflow run.
5. You’ll see the build job. Click on it.
6. You can now see the execution of each step: “Checkout repository code”, “Set up Python environment”, “Install dependencies”, and “Run our Python script”.
7. Click on “Run our Python script” to expand its logs. You should see Hello from GitHub Actions! printed!

Congratulations! You’ve just built and executed your first CI/CD workflow with GitHub Actions! This might seem simple, but you’ve grasped the fundamental concepts that scale to complex, multi-stage pipelines.

Mini-Challenge: Enhance Your Workflow!

Now that you’ve got the hang of it, let’s make a small enhancement.

Challenge: Modify your my-first-workflow.yml to achieve the following:

1. Make the workflow trigger not only on push events but also when a pull_request is opened, synchronized, or reopened for the main branch.
2. Add a new step before “Run our Python script” that prints a custom message like “Starting application logic…” to the console.

Hint:

• For multiple events, remember the on: syntax.
• For a new step, think about how you added the previous name: and run: commands.

What to observe/learn:

• How to configure multiple trigger events for a workflow.
• How to insert new steps into an existing job and see their output in the logs.
• Trigger a new run by pushing a small change, and then by opening a pull request to main.

Take your time, try to solve it independently. If you get stuck, don’t worry, hints are there to guide you!

# .github/workflows/my-first-workflow.yml
name: My First Python CI Workflow

on:
  push:
    branches: [ main ] # Trigger on pushes to the main branch
  pull_request:
    branches: [ main ] # Trigger on pull requests targeting the main branch

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

      - name: Set up Python environment
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

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

      - name: Starting application logic message
        run: echo "Starting application logic..."

      - name: Run our Python script
        run: python hello.py

Common Pitfalls & Troubleshooting

Even experienced developers run into issues. Here are some common pitfalls with GitHub Actions and how to troubleshoot them:

1. YAML Syntax Errors:

   • Pitfall: YAML is sensitive to indentation and spacing. A single incorrect space can cause a workflow to fail with a parsing error.
   • Troubleshooting:
     • Use a YAML linter (many IDEs have them built-in, like VS Code with the YAML extension).
     • Double-check indentation. YAML typically uses 2 spaces, not tabs.
     • Look carefully at the error message in GitHub Actions; it often points to the exact line number.

2. Incorrect uses: Action Versions:

   • Pitfall: Using an outdated or non-existent action version (e.g., actions/checkout@v100 if v4 is the latest).
   • Troubleshooting:
     • Always refer to the GitHub Marketplace or the action’s repository for the latest stable version.
     • Using specific versions (@v4) is good; using @main or @master can be risky as it might introduce breaking changes without warning.

3. Permissions Issues:

   • Pitfall: Your workflow might try to perform an action (like pushing to a protected branch or accessing a secret) without the necessary permissions.
   • Troubleshooting:
     • GitHub Actions runs with a default GITHUB_TOKEN that has specific permissions. Check the official documentation for GITHUB_TOKEN permissions.
     • If you need more elevated permissions (e.g., to create releases), you might need to use a Personal Access Token (PAT) stored as a GitHub Secret. However, be cautious with PATs due to security implications.

4. Debugging Workflow Runs:

   • Pitfall: A step fails, but the error message isn’t clear.
   • Troubleshooting:
     • Check Logs Thoroughly: GitHub Actions provides detailed logs for each step. Expand the failing step and read the output carefully. Error messages are often at the very end.
     • Add echo Statements: Just like you’d use print() in Python, you can add echo commands in run: steps to print variable values or status messages to the logs for debugging purposes.
     • Rerun Jobs: You can always re-run failed jobs or the entire workflow from the GitHub UI.

Summary

You’ve taken a significant leap today! We’ve covered the fundamental principles of CI/CD and implemented our very first automated workflow using GitHub Actions.

Here’s what we learned:

• Continuous Integration (CI) and Continuous Delivery (CD) automate the software development lifecycle, enhancing speed and reliability.
• GitHub Actions provide an integrated, powerful CI/CD solution directly within GitHub.
• Workflows are defined in YAML files (.github/workflows/) and orchestrate automated processes.
• Events trigger workflows (e.g., push, pull_request).
• Jobs are independent sets of steps that run on a runner.
• Steps are individual tasks within a job, which can be run: commands or reusable uses: actions.
• We successfully created a workflow to checkout code, set up a Python environment, install dependencies, and run a script, observing the output in GitHub’s Actions tab.

You’re now equipped with the basic building blocks of modern CI/CD! In the upcoming chapters, we’ll delve deeper into more complex workflows, integrate with containerization tools like Docker, and explore other CI/CD platforms like Jenkins, building on this foundational understanding.

References

• GitHub Actions Documentation
• GitHub Actions: checkout Action
• GitHub Actions: setup-python Action

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.