GitHub Actions Tutorial & Examples (CI/CD Step-by-Step Guide)

Today, software teams develop faster than ever, but only if their delivery pipelines can keep pace. Manual builds, testing, and deployments do not scale reliably in modern software teams. This is where GitHub Actions comes into play.

In this guide, you will find information on what GitHub Actions is, why it is important for modern CI/CD processes and methods of continuous integration and delivery, and how to utilise GitHub Actions properly, from your initial workflow to production-ready pipelines.

Who this guide is for:

CI/CD beginners, developers looking to automate their build process, and DevOps engineers seeking to design and build scalable CI/CD pipelines.

By the time you finish this tutorial, you will be able to:

• Develop and manage GitHub Actions workflows
• Automate the build-test-deploy process
• Use secrets and permissions to secure your pipelines (Security)
• Implement best practices that are used in real-life CI/CD systems

What Is GitHub Actions?

GitHub Actions is a CI/CD and automation service that is built into GitHub. It enables you to automate tasks such as building, testing, and deploying code whenever an event happens in your repository.

Rather than having to use external CI servers, GitHub Actions is integrated into GitHub itself, right where your code lives and in your pull requests.

Typical automation jobs include:

• Running tests on every push
• Reviewing pull requests
• Building and pushing Docker images
• Deploying applications
• Running scheduled maintenance jobs

Why Use GitHub Actions?

GitHub Actions has been well-received because it removes friction when it comes to CI/CD.

• Native GitHub integration – no need for extra tools or servers
• Faster setup times than traditional CI tools
• Massive ecosystem due to the GitHub marketplace
• Scales from small projects to enterprise CI/CD

If you are already using GitHub, it is probably the easiest CI/CD solution for your team.

Core Concepts of GitHub Actions (Foundations You Must Understand)

Workflows

A workflow is an automated process that is defined in a YAML file located in .github/workflows/.

• Triggered by events such as a push or pull request
• May include one or more jobs
• Represents a complete pipeline

Events and triggers

Events determine when a workflow will run.

Common triggers include:

• push – Code pushed to a branch
• pull_request – PR is opened or updated
• workflow_dispatch – manual trigger
• schedule – cron-based execution
• release – when a GitHub release is created
• workflow_call – used for reusable workflows

Selecting the appropriate triggers helps keep pipelines lean and reliable.

Jobs and Execution Flow

A job is a set of steps that execute on the same runner.

• Jobs execute in parallel by default
• Using needs to establish dependencies
• Each job executes in a clean environment unless artefacts or caches are explicitly shared.

Jobs enable breaking pipelines into stages such as build, test, and deploy.

Steps and Actions

Steps are individual actions within a job.

There are two types of steps:

• Run steps: Shell commands
• Action steps: reusable actions from the marketplace
• Composite actions: combine multiple steps into reusable logic

Actions reduce boilerplate code and promote consistency in automation across multiple projects.

Runners and runs-on

The runs-on keyword defines which runner environment a job uses.

• GitHub-hosted runners – managed by GitHub
• Self-hosted runners – managed by you

Typical runner options

• ubuntu-latest
• windows-latest
• macos-latest

The choice of runner impacts execution speed, environment, and cost.

GitHub Actions Workflow Syntax (YAML Explained)

GitHub Actions workflows are authored in YAML and consist of the following:

• name – name of the workflow
• on – events trigger the workflow
• jobs – automation tasks
• steps – commands or actions

Minimal example:

name: CI Pipeline
on: [push]
jobs:
 build:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v4
     - run: echo "Hello, GitHub Actions"

YAML is sensitive to indentation, and incorrect spacing is one of the most common issues in a workflow.

Creating Your First GitHub Actions Workflow (Step-by-Step)

Method 1: Create a Workflow Using the GitHub UI

• Create workflows by going to the Action tab of your repository.
• Use templates that are available for popular technologies
• Great if you are new to GitHub and want to get started using GitHub’s Action service easily; however, this approach is better suited for simple projects and experimentation.

Method 2: Create a Workflow Locally (Recommended)

• Create .yml files for your workflows.
• Just like with any other software, commit your workflow changes to the code repository.
• Collaboration, version control and code review are much simpler through this method.

This is the preferred method of creating workflows for all teams and production environments.

GitHub Actions Examples (Real-World CI/CD Use Cases)

Node.js CI with GitHub Actions

Below is a complete, real-world example of a GitHub Actions workflow for a Node.js project. This workflow automatically installs dependencies, runs tests, and validates the application on every push and pull request.

It also demonstrates matrix builds and dependency caching, which are commonly used in professional CI pipelines built with GitHub Actions.

name: Node.js CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18, 20]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

What this workflow does

• Triggers automatically on every push to the main branch and on all pull requests
• Runs the job on Ubuntu using a GitHub-hosted runner
• Tests multiple Node.js versions (18 and 20) using a matrix strategy
• Caches npm dependencies to speed up future workflow runs
• Fails fast if dependency installation or tests fail

This pattern represents a standard continuous integration setup used in real-world production projects and can be easily extended with linting, build steps, or deployment stages.

Below are additional common CI/CD use cases that can be implemented using similar patterns.

Build and Test a Python Project

• Establish Python version control
• Set up dependency management
• Implement automated test procedures
• Automatically fail builds when an error occurs

Build and Push Docker Images

• Utilise secrets for authentication and security
• Build and tag Docker images
• Publish Docker images to container registries

Running Shell Scripts on a Runner

• Run shell scripts on continuous integration servers
• User exit codes of scripts to determine success
• Debugging issues related to environment configuration

Deploying a Static Website

• CI → CD workflow
• Deploy to hosting providers
• Use rollback-friendly deployment strategies

Working with Secrets and Environment Variables

As you begin to automate your build and deployment tasks, your workflows will need to access sensitive information such as API keys, tokens, passwords, or cloud credentials. GitHub Actions has a secure way of handling this using secrets and environment variables, but it is important to understand when and how to use each.

What secrets are and why they’re encrypted

Secrets are encrypted values that are stored in a secure fashion in GitHub. They are never logged and will be automatically masked if they are accidentally printed. This makes them ideal for any use case that requires secrecy.

Repository vs organisation secrets

• Repository secrets: accessible only to a specific repo
• Organisation secrets: accessible from multiple repositories

How secrets are injected into workflows

Secrets are injected into the workflow at runtime using syntax like ${{ secrets.MY_SECRET }}, which means they are never hard-coded in your YAML files.

Environment variables, on the other hand, are used for non-sensitive configuration values such as app modes, file paths, or feature flags

These can be defined at:

• Environment variable scope (available everywhere)
• Job scope (available to a specific job)
• Step scope (most granular control)

When to use secrets vs normal variables

• Use secrets or credentials, tokens, and private keys
• Use environment variables or values that can be safely exposed

Best practices for secure configuration management

• Never commit secrets to your repository
• Scope secrets as narrowly as possible
• Rotate secrets regularly
• Use least-privilege access for tokens
• Avoid printing environment values in logs.

Advanced GitHub Actions Features (Without Overengineering)

Matrix Builds

strategy:
  matrix:
    node-version: [18, 20]

Run jobs on:

• Multiple operating systems
• Multiple language versions

Useful for compatibility testing, but avoid unnecessary complexity.

Caching Dependencies

Caching dependencies makes CI blazing fast by reusing them.

• Use the cache key wisely.
• Invalidates caches when dependencies change
• Avoid caching build artifacts unnecessarily.

Workflow Permissions and Security

• Default permissions are restrictive.
• Use the permissions keyword.
• Follow least-privilege principles

permissions:
  contents: read
  packages: write

Self-Hosted Runners

Useful when:

• GitHub-hosted runners aren’t enough
• Compliance or performance requirements exist.

Trade-off: higher maintenance responsibility.

GitHub Actions for CI/CD Pipelines

GitHub Actions makes it easier to implement end-to-end CI/CD pipelines without adding complexity. A typical pipeline starts with continuous integration, where the code is automatically compiled and tested for each push or pull request, followed by managed deployment.

• Branch workflows help implement the concept of separation of concerns. Feature branches can be used for testing, while the main branch is reserved for deployment.
• Environment-based deployment makes it possible to move the same build from the staging environment to production with confidence.
• Release and production pipelines can be triggered manually or on version tags, giving control over when the code is deployed.

This approach ensures that the pipelines are always reliable, predictable, and maintainable.

Using GitHub Actions with GitOps and Kubernetes

• GitHub Actions is an ideal choice to use with GitOps pipelines
• Use code to deploy infrastructure.
• Automate your deployments to Kubernetes clusters.
• Integrate CI/CD and Infrastructure as Code (IAC).

GitHub Actions is typically used for CI and image publishing, while GitOps tools handle continuous deployment to Kubernetes.

Common GitHub Actions Mistakes

• Hardcoding secrets
• Not caching dependencies
• Bigger is not always better (over-engineering)
• Using the wrong permissions
• Slow because of all the notifications (noisy).

In most instances, the issue lies in the design rather than the tool

GitHub Actions Best Practices

• Divide large workflows into smaller ones
• Utilise action/workflow reusability
• Lock-action versions
• Protect secrets and permissions
• Monitor and continuously improve pipelines

Frequently Asked Questions

Shivam Mahajan

Shivam Mahajan is an editor skilled in SysOps, Tech, and Cloud. With experience at AttuneOps and other companies, he simplifies complex technical material for easy understanding.