Chapter 13: CI/CD Basics with GitHub Actions

Introduction: Automating Your Development Journey

Welcome to Chapter 13! So far, we’ve mastered Git for local version control, learned how to collaborate effectively with GitHub, navigated complex branching strategies, and resolved tricky merge conflicts. You’re becoming a Git and GitHub pro! But what if we could make our development process even smoother, faster, and more reliable?

That’s where CI/CD comes in. CI/CD stands for Continuous Integration and Continuous Delivery (or Continuous Deployment), and it’s a set of practices that automate much of the software development lifecycle. Imagine pushing your code, and automatically, it’s tested, checked for errors, and even deployed without you lifting another finger. Sounds magical, right?

In this chapter, we’re going to demystify CI/CD and learn how to implement these powerful practices using GitHub Actions. GitHub Actions is GitHub’s built-in platform for automating tasks directly within your repository. By the end of this chapter, you’ll be able to set up your first automated workflow, ensuring your code is always in a releasable state, and you’ll understand the core concepts behind modern software delivery.

Ready to make your code work harder, so you don’t have to? Let’s dive in!

Core Concepts: What is CI/CD and Why GitHub Actions?

Before we start writing any automation scripts, let’s get a solid grasp of what CI/CD really means and why it’s become an indispensable part of modern software development.

What is CI/CD? The Automation Superhighway

CI/CD is more than just tools; it’s a philosophy focused on improving the quality and speed of software delivery through automation. It typically breaks down into two main parts:

Continuous Integration (CI):
- What it is: Developers frequently merge their code changes into a central repository (like main or develop). Each merge triggers an automated build and test process.
- Why it matters:
  - Early Bug Detection: Catch integration issues and bugs almost immediately after they’re introduced, making them easier and cheaper to fix.
  - Faster Feedback: Developers get quick feedback on the health of their code, allowing for rapid iteration.
  - Reduced Integration Problems: Prevents “integration hell” where large, infrequent merges lead to massive conflicts and broken builds.
  - Consistent Builds: Ensures that the software can always be built successfully from the repository.
Continuous Delivery (CD) / Continuous Deployment (CD):
- What it is:
  - Continuous Delivery: Extends CI by ensuring that all code changes are automatically built, tested, and prepared for release to a production environment. This means a new release can be deployed at any time with the push of a button.
  - Continuous Deployment: Takes Continuous Delivery a step further by automatically deploying every change that passes all tests to production, without human intervention.
- Why it matters:
  - Rapid Releases: Deliver new features and bug fixes to users much faster.
  - Reduced Risk: Smaller, more frequent releases are less risky than large, infrequent ones.
  - Improved Quality: Automated testing at every stage reduces the chance of defects reaching users.
  - Increased Confidence: Teams gain confidence in their ability to release reliable software on demand.

Think of it like an assembly line for your code: CI ensures each new part fits perfectly and works, while CD ensures the complete product is ready to ship, or even ships itself, automatically!

Here’s a simplified visual of a typical CI/CD pipeline:

graph TD A["Developer Pushes Code"] --> B{"GitHub Event Triggered"}; B --> C["CI Workflow Starts"]; C --> D["Job: Build & Test"]; D --> D1["Step: Checkout Code"]; D1 --> D2["Step: Setup Environment"]; D2 --> D3["Step: Install Dependencies"]; D3 --> D4["Step: Run Unit Tests"]; D4 --> D5["Step: Run Lint/Static Analysis"]; D5 --> F{"CI Result: Success?"}; F -->|Yes| G["CD Workflow (Optional)"]; G --> H["Job: Deploy to Staging"]; H --> I["Manual Approval (Optional)"]; I --> J["Job: Deploy to Production"]; F -->|No| K["Notify Developer & Stop"]; J --> L["User Accesses New Features"];

This diagram shows how a code push can trigger a CI process, which, if successful, can then lead to a CD process.

Introducing GitHub Actions: Your Personal Automation Assistant

GitHub Actions is GitHub’s native CI/CD platform. It allows you to automate tasks directly in your repository, from simple notifications to complex multi-stage deployments. It’s event-driven, meaning your workflows are triggered by events happening in your repository, like a push to a branch, a pull_request being opened, or even a scheduled time.

Key Components of GitHub Actions:

Workflow: A configurable automated process defined by a YAML file in your repository (.github/workflows/). Each workflow consists of one or more jobs.
Event: A specific activity in your repository that triggers a workflow. Examples include push, pull_request, issue_comment, schedule.
Job: A set of steps that execute on the same runner. A workflow can have multiple jobs that run in parallel or sequentially.
Step: An individual task within a job. A step can execute a command (like npm install) or run an Action.
Action: A reusable unit of work. Actions are the smallest building block of a workflow. You can write your own, or use thousands of pre-built actions from the GitHub Marketplace (e.g., actions/checkout, actions/setup-node).
Runner: A server that runs your workflow. GitHub provides hosted runners (Linux, Windows, macOS) or you can host your own self-hosted runners.

Think of it like this: You write a “recipe” (the Workflow YAML file) that says, “When this ’event’ happens (e.g., someone adds new code), run these ‘jobs’ (e.g., build the app, run tests) on a ‘runner’ (a virtual machine). Each ‘job’ has a list of ‘steps’ to follow (e.g., get the code, install dependencies, run tests), and some ‘steps’ use pre-made ‘actions’ (e.g., a ‘step’ to get the code uses the checkout ‘action’).”

Workflow File Structure: The YAML Recipe

GitHub Actions workflows are defined using YAML files. These files live in a special directory: .github/workflows/ at the root of your repository.

A typical workflow file looks something like this:

# .github/workflows/ci.yml

name: My First CI Workflow # A human-readable name for your workflow

on: # Defines when the workflow runs
  push: # Runs on every push to specific branches
    branches:
      - main
      - develop
  pull_request: # Runs when a pull request is opened, synchronized, or reopened
    branches:
      - main
      - develop

jobs: # Defines one or more jobs to run
  build: # The ID of the job (e.g., 'build', 'test', 'deploy')
    runs-on: ubuntu-latest # The type of runner to use (e.g., ubuntu-latest, windows-latest)

    steps: # A sequence of tasks to perform in the job
      - name: Checkout code # A descriptive name for the step
        uses: actions/checkout@v4 # Uses a community action to check out your repository code

      - name: Setup Node.js environment # Another descriptive name
        uses: actions/setup-node@v4 # Uses a community action to set up Node.js
        with:
          node-version: '20.x' # Specifies the Node.js version to use. As of late 2025, Node.js 20.x is a stable LTS.

      - name: Install dependencies
        run: npm install # Executes a command-line program

      - name: Run tests
        run: npm test # Executes another command-line program

      - name: Run linting
        run: npm run lint # Assuming you have a lint script defined in package.json

Don’t worry if this looks like a lot right now! We’ll build this up step by step. The key is to understand the hierarchy: workflow -> jobs -> steps -> actions/commands.

Step-by-Step Implementation: Building Your First GitHub Action

Let’s get practical! We’ll create a simple Node.js project and then set up a GitHub Actions workflow to automatically lint and test our code every time we push changes.

Prerequisites

You should have Git installed (we’ll assume a version like Git 2.46.0 for 2025-12-23, but any recent version will work). Verify with git --version.
You should have Node.js and npm installed. We’ll use Node.js 20.x LTS for our CI/CD setup. Verify with node -v and npm -v.
A GitHub account and a basic understanding of creating repositories.

Step 1: Create a Sample Node.js Project

If you already have a Node.js project you’re comfortable with, feel free to use that. Otherwise, let’s create a fresh one.

Create a new directory for your project:
```
mkdir ci-cd-demo
cd ci-cd-demo
```
Initialize a Node.js project:
```
npm init -y
```
This creates a package.json file with default settings.

Create a simple index.js file:

echo "console.log('Hello from CI/CD!');" > index.js

Initialize a Git repository and make your first commit:

git init
git add .
git commit -m "Initial project setup"

Create a new repository on GitHub. Go to github.com/new, give it a name like ci-cd-demo, make it public or private, and do not initialize with a README.

Link your local repository to the GitHub remote:

git remote add origin https://github.com/YOUR_USERNAME/ci-cd-demo.git
git branch -M main
git push -u origin main

Replace YOUR_USERNAME with your actual GitHub username.

Great! You now have a basic Node.js project linked to a GitHub repository.

Step 2: Create the Workflow Directory

GitHub Actions workflows live in a specific folder structure. Let’s create it.

From your project’s root directory (ci-cd-demo), create the necessary folders:
```
mkdir -p .github/workflows
```
The -p flag ensures that parent directories (.github) are created if they don’t exist.

Step 3: Define Your First Workflow (Basic CI - Lint & Test)

Now for the exciting part! We’ll create our ci.yml file to define our workflow.

Create a new file named ci.yml inside the .github/workflows/ directory:

# Using a text editor, open: .github/workflows/ci.yml
# Or, if you're comfortable with command line:
# touch .github/workflows/ci.yml

Add the following content to .github/workflows/ci.yml:

# .github/workflows/ci.yml

# This is the name of our workflow. It will appear in the GitHub Actions tab.
name: Node.js CI

# This defines when the workflow will run.
# We want it to run whenever code is pushed to the 'main' branch
# or when a pull request is opened/updated targeting 'main'.
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

# A workflow is made up of one or more jobs.
jobs:
  # This is our first and only job, named 'build'.
  build:
    # This specifies the type of runner (virtual machine) to use.
    # 'ubuntu-latest' is a common choice for Linux-based environments.
    runs-on: ubuntu-latest

    # These are the steps (individual tasks) that the 'build' job will execute.
    steps:
      # Step 1: Check out our repository code.
      # The 'actions/checkout@v4' action downloads our code into the runner.
      # 'v4' is the latest stable major version as of 2025.
      - name: Checkout repository
        uses: actions/checkout@v4

      # Step 2: Set up the Node.js environment.
      # The 'actions/setup-node@v4' action installs Node.js on the runner.
      # We specify '20.x' to use the latest Node.js 20 LTS version.
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          cache: 'npm' # This caches npm dependencies to speed up subsequent runs.

      # Step 3: Install project dependencies.
      # This runs the 'npm install' command, just like you would locally.
      - name: Install dependencies
        run: npm install

      # Step 4: Run a simple lint check.
      # We don't have a lint script yet, so for now, we'll just echo a message.
      # We'll add a real lint step shortly.
      - name: Run lint check
        run: echo "Linting step placeholder..."

      # Step 5: Run tests.
      # We don't have any tests yet, so this will likely fail or do nothing.
      # We'll add a real test script next.
      - name: Run tests
        run: npm test

Explanation of each section:

name: Node.js CI: This is simply a label that will show up in the GitHub Actions tab, making it easy to identify your workflow.
on: push and on: pull_request: These are our events. We’re telling GitHub, “Hey, run this workflow whenever someone pushes code to the main branch, or when a pull request is opened/updated targeting main.”
jobs: build: This defines a single job named build. A workflow can have multiple jobs, but for now, one is enough.
runs-on: ubuntu-latest: This specifies that our build job should run on the latest version of an Ubuntu Linux virtual machine provided by GitHub. These are called runners.
steps:: This is a list of individual steps that the build job will execute in order.
- - name: Checkout repository and uses: actions/checkout@v4: This step uses a pre-built action from the GitHub Marketplace. actions/checkout@v4 is super common; it simply clones your repository’s code onto the runner so subsequent steps can access it.
- - name: Setup Node.js and uses: actions/setup-node@v4: Another essential action. This one sets up a Node.js environment on the runner. We use with: node-version: '20.x' to specify that we want Node.js version 20 (which is an LTS version as of late 2025). The cache: 'npm' line helps speed up npm install by caching dependencies.
- - name: Install dependencies and run: npm install: This step executes a standard shell command (npm install) on the runner to get all our project’s Node.js packages.
- - name: Run lint check and run: echo "Linting step placeholder...": For now, this is a placeholder. We’ll add a real linting tool in a moment.
- - name: Run tests and run: npm test: This step runs the test script defined in our package.json.

Step 4: Push to GitHub and Observe

Now, let’s commit our new workflow file and push it to GitHub. This push event should trigger our workflow!

Add the new workflow file to Git:
```
git add .github/workflows/ci.yml
```

Commit the changes:

git commit -m "Add basic Node.js CI workflow"

Push to GitHub:
```
git push origin main
```
Observe on GitHub:
- Open your browser and navigate to your GitHub repository (https://github.com/YOUR_USERNAME/ci-cd-demo).
- Click on the “Actions” tab at the top.
- You should see your “Add basic Node.js CI workflow” commit listed, with a yellow dot indicating that the workflow is running.
- Click on the workflow run. You’ll see the Node.js CI workflow name, and inside it, the build job.
- Click on the build job to see the individual steps executing. You’ll see “Checkout repository”, “Setup Node.js”, “Install dependencies”, “Run lint check”, and “Run tests”.
- Notice that “Run tests” might show a warning or failure because we haven’t defined a test script yet. That’s perfectly normal and expected! This is how CI gives us feedback.

Congratulations! You’ve just set up and run your first GitHub Actions workflow!

Step 5: Add a Simple Test and Lint Script

Let’s make our CI workflow more meaningful by adding a simple test and a lint command.

Modify package.json to include a test and lint script. Open your package.json file and locate the "scripts" section. Change it to look like this:

// package.json
{
  "name": "ci-cd-demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "node test.js", // We'll create test.js next
    "lint": "echo 'No real linting configured yet, but this passed!'" // A simple placeholder for linting
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

We’ve updated the test script to run a file named test.js (which we’ll create) and added a lint script that just prints a success message for now.

Create a simple test.js file:

echo "
const assert = require('assert');

function add(a, b) {
    return a + b;
}

assert.strictEqual(add(1, 2), 3, 'add(1, 2) should be 3');
assert.strictEqual(add(-1, 1), 0, 'add(-1, 1) should be 0');
assert.notStrictEqual(add(2, 2), 5, 'add(2, 2) should not be 5');

console.log('All tests passed!');
" > test.js

This test.js file uses Node.js’s built-in assert module to perform a few basic checks on an add function.

Update your ci.yml to use the new lint script. Open .github/workflows/ci.yml again. Find the Run lint check step and change its run command:

# .github/workflows/ci.yml

# ... (previous parts of the workflow) ...

      - name: Run lint check
        run: npm run lint # Now this will execute the 'lint' script from package.json

      - name: Run tests
        run: npm test # This will execute the 'test' script from package.json

Commit and Push:

git add .
git commit -m "Add simple test and lint scripts, update CI workflow"
git push origin main

Observe on GitHub again:
- Go back to the “Actions” tab in your GitHub repository.
- You’ll see a new workflow run triggered by your latest commit.
- This time, when you click into the run and then the build job, you should see both “Run lint check” and “Run tests” steps complete successfully (with green checkmarks!).

You’ve now successfully integrated automated linting and testing into your development workflow! Every time you or a teammate pushes code, these checks will automatically run, providing immediate feedback on code quality and correctness.

Mini-Challenge: Expanding Your Workflow Triggers

You’ve seen how push and pull_request events work. Now, let’s make your workflow even more robust.

Challenge: Modify your ci.yml workflow to:

Trigger not only on push and pull_request to main, but also when a release is published.
Add a new step to the build job that checks if a README.md file exists in the repository. If it doesn’t, the step should fail.

Hint:

For the release event, look up on: release in the GitHub Actions documentation. You’ll likely use types: [published].
For checking file existence, you can use a simple shell command combined with conditional logic. For example, test -f README.md will exit with a non-zero status (failure) if README.md doesn’t exist.

What to observe/learn:

How to add multiple event triggers to a workflow.
How to add custom shell commands as steps and use their exit status to determine step success/failure.
The importance of documentation (like a README.md) in a project.

Take your time, try to figure it out, and remember to commit and push your changes to see the workflow run on GitHub!

Need a little nudge?

Here’s how you might add the release event:

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  release: # New event!
    types: [published] # Triggers when a new release is published

And for checking the README.md file:

      - name: Check for README.md
        run: |
          if [ ! -f README.md ]; then
            echo "Error: README.md file is missing!"
            exit 1 # Exit with a non-zero code to indicate failure
          else
            echo "README.md exists. Good job!"
          fi

Remember to add this new step within your jobs.build.steps section.

Common Pitfalls & Troubleshooting

Even with the best intentions, workflows can sometimes go awry. Here are a few common issues and how to troubleshoot them:

YAML Syntax Errors (Indentation Hell):
- Pitfall: YAML is very sensitive to whitespace and indentation. A single incorrect space can break your workflow.
- Troubleshooting: GitHub provides excellent in-line error messages in the “Actions” tab if your YAML is malformed. Pay close attention to these. Use a good text editor (like VS Code) with YAML extensions that highlight syntax errors. Tools like YAML Lint can also help.
Missing runs-on or Incorrect Runner:
- Pitfall: Forgetting to specify runs-on or specifying a runner that doesn’t exist or isn’t available to your repository.
- Troubleshooting: Check the workflow run logs on GitHub. If the runner can’t be found, the job won’t even start, and you’ll see an error message at the job level. Ensure you’re using a valid GitHub-hosted runner (e.g., ubuntu-latest, windows-latest, macos-latest) or a properly configured self-hosted runner.
Permissions Issues:
- Pitfall: Your workflow might try to perform an action (like pushing to a protected branch, creating a release, or commenting on an issue) without sufficient permissions.
- Troubleshooting: GitHub Actions runs with a temporary GITHUB_TOKEN that has limited permissions. If you need more permissions (e.g., to write to a different repository or interact with external services), you might need to:
  - Adjust the permissions key in your workflow file (e.g., permissions: contents: write).
  - Use a Personal Access Token (PAT) stored as a GitHub Secret (though GITHUB_TOKEN is preferred for most in-repo actions).
  - Check your repository’s “Settings > Actions > General” for workflow permissions.
Actions Failing Silently (or with Cryptic Errors):
- Pitfall: A step might fail, but the error message isn’t clear, or the step simply hangs.
- Troubleshooting: Always check the detailed logs for each step! Click on the failing step in the GitHub Actions UI. Often, the full error message from your script (npm test, npm run lint, etc.) will be printed there. Look for stack traces, specific error codes, or “command not found” messages. Sometimes, adding set -xeo pipefail at the start of your run commands can help make shell script failures more explicit.

Summary: Your Automated Future Awaits!

Phew! You’ve just taken a massive leap into the world of modern software development. In this chapter, we covered:

What CI/CD is: Continuous Integration for frequent merges and automated testing, and Continuous Delivery/Deployment for rapid, reliable releases.
Why CI/CD matters: Faster feedback, earlier bug detection, reduced risk, and increased confidence in your code.
Introducing GitHub Actions: GitHub’s built-in platform for automating tasks based on repository events.
Key components: Workflows, Events, Jobs, Steps, Actions, and Runners.
Building your first workflow: We created a ci.yml file to automatically checkout code, set up Node.js, install dependencies, run lint checks, and execute tests.
Troubleshooting: Common issues like YAML syntax, runner problems, and permissions.

You now have the foundational knowledge to automate crucial parts of your development workflow. This isn’t just a convenience; it’s a best practice that leads to higher quality software and happier development teams.

What’s next? In the upcoming chapters, we’ll continue to build on this foundation. We might explore more advanced deployment scenarios, delve into security scanning within CI/CD, or compare GitHub Actions to other CI/CD tools. For now, take pride in your new automation superpowers!

References

GitHub Actions Documentation: The official and most comprehensive resource for all things GitHub Actions.
- https://docs.github.com/en/actions
GitHub Actions Marketplace: Discover thousands of pre-built actions to integrate into your workflows.
- https://github.com/marketplace?type=actions
Git Official Documentation: For general Git commands and concepts.
- https://git-scm.com/doc
Node.js LTS Releases: Information on current and upcoming Node.js Long Term Support versions.
- https://nodejs.org/en/about/releases
YAML Syntax Reference: A quick guide to YAML syntax, useful for debugging workflow files.
- https://yaml.org/

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