What Are GitHub Actions and How to Run Them Locally?

This guide shows you exactly how. We'll cover the fundamentals of GitHub Actions and walk you through the process of running and debugging your CI/CD workflows locally.

Tired of pushing a tiny change to a workflow file, waiting five minutes for the job to run, only to see it fail on a simple typo?

That slow, frustrating cycle of committing, pushing, and waiting is a common bottleneck that clutters your repository with "fix typo" commits and kills your momentum. What if you could test your entire automation pipeline in seconds, right from your local machine, before ever running git commit ?

A Deeper Look into GitHub Actions

At its core, GitHub Actions is an automation tool built directly into the GitHub platform. It enables you to automate, customize, and execute your software development workflows directly within your repository.

Think of it as a configurable automated process that responds to specific events, such as a code push, a pull request creation, or even on a defined schedule. This makes it an incredibly powerful tool for CI/CD (Continuous Integration/Continuous Delivery).

Key benefit of GitHub Actions

• Event-Driven: Workflows are triggered automatically by events, such as code pushes.

• YAML Configuration: Workflows are defined as code in YAML files.

• Repository Based: Stored directly in your repository at .github/workflows.

• Versatile: A single repository can host multiple workflows for different tasks.

Test automation isn’t just about writing good scripts—it’s about creating a feedback engine that runs automatically, scales with your code, and ensures quality in real-time. GitHub Actions makes that possible with minimal setup and massive value. → LinkedIn Post

What Are GitHub Actions Used For?

GitHub Actions are versatile and can be used for a wide range of automation tasks within the software development lifecycle. Their primary purpose is to automate workflows, making development faster and more reliable.

Here are some common use cases:

• Continuous Integration (CI): This is the most popular use for GitHub Actions. You can create workflows that automatically build your code and run tests every time a developer pushes code to the repository or opens a pull request. This ensures that new changes integrate smoothly with the existing repository code.

• Continuous Deployment (CD): Beyond testing, you can use GitHub Actions to automate the deployment of your application to various environments, like staging or production. The process of testing pull requests and deploying becomes a streamlined, one-click (or even zero-click) operation.

• Task Automation: You can automate almost any repetitive task. This includes labeling new issues, sending notifications to a Slack channel, managing branches, or even generating documentation. By handling this repetitive code, developers can focus on more important work.

• Code Quality and Reviews: Automate code analysis tools to check for style inconsistencies, security vulnerabilities, or other issues on every pull request. This facilitates better code reviews and maintains a high standard of code quality across the project.

The Building Blocks of a GitHub Actions Workflow

To effectively utilize GitHub Actions, it is essential to understand the components of GitHub Actions. These are all defined within a .yml or .yaml file, which serves as the blueprint for your automation. A GitHub Actions workflow is composed of one or more jobs that can run sequentially or in parallel.

A specific event triggers each workflow run and executes the defined jobs on a runner. Let's break down the key parts of a workflow file.

The On Trigger: Starting Your Automation

Every GitHub Actions workflow must have a trigger, which is defined by the' on' keyword. This specifies the event that will cause the workflow to run. An event is a specific activity within your GitHub repository.

Common triggers include:

• push: Runs the workflow when someone pushes commits to a specific branch. This is a common trigger for running build jobs and tests in response to a push event.

• pull_request: Triggers the workflow when a pull request is opened, updated, or closed. This is ideal for running checks before merging code.

• schedule: Allows you to run a workflow at a specific time, similar to a cron job.

• workflow_dispatch: This feature allows the workflow to be triggered manually from the GitHub UI, providing on-demand control over your automation tasks. This is a great way to run a GitHub Actions workflow manually.

Defining Jobs for Your Workflow

A workflow consists of one or more jobs. A job is a set of steps that execute on the same runner. By default, jobs run in parallel. However, you can configure job dependencies to ensure they run in a sequential order, where one job must complete successfully before the next one begins. For example, you might have several parallel build jobs for different platforms, followed by a single packaging job that depends on all of them.

Specifying the Runner Environment (runs-on)

Each job needs a virtual environment to run in. The runs-on keyword specifies the type of machine on which to run the job. GitHub provides GitHub-hosted runners with various operating systems, including Ubuntu Linux, Microsoft Windows, and macOS. GitHub maintains these runners and are ready to use.

For example, to use the latest version of Ubuntu, you would specify:

runs-on: ubuntu-latest

Alternatively, for more control over the hardware or software environment, you can set up self-hosted runners. These are machines that you host and manage yourself, whether on-premises or with a cloud provider. Using self-hosted runners gives you complete control over the operating system and installed dependencies.

Detailing Steps within a Job

The heart of a job is its steps. Steps are individual tasks that run in sequence within a job. A step can be a shell command or an action.

• run: This executes command-line programs using the operating system's shell. You can use it to run scripts, install dependencies, or perform any other command-line task.

• uses: This keyword tells the job to retrieve an action, which is a reusable unit of code. Actions are a powerful feature of the GitHub Actions ecosystem. You can find thousands of pre-built actions in the GitHub Marketplace to perform common tasks, or you can create your own. This reusable extension model helps prevent the need for repetitive code.

Here's an example of a very simple GitHub Actions workflow:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
name: Simple CI

on: [push]

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

      - name: Echo a message
        run: echo "Hello, GitHub Actions!"

In this example, the workflow is triggered on every push. It has a single job named build that runs on an

ubuntu-latest

runner. The job has two steps: the first uses the official checkout action to download the repository code to the runner, and the second runs a simple echo command.

Ready to streamline your development process even further with powerful integrations? Rocket.new offers seamless GitHub integration to help you manage your projects effortlessly.

Strat Building Your App Now!

The Local Advantage: Why Run GitHub Actions on Your Machine?

While GitHub Actions are designed to run in the cloud, developing and debugging workflows can be cumbersome. The typical cycle involves editing the .yaml file, committing, pushing to GitHub, and waiting for the workflow run to start, only to discover a simple syntax error. This feedback loop can be slow and frustrating.

Running your GitHub Actions workflows locally provides several key benefits:

• Faster Feedback: Test changes to your workflow files in seconds, not minutes. You can iterate quickly without cluttering your git repository history with minor commits.

• Cost Savings: GitHub provides a limited number of free minutes for GitHub-hosted runners. Running workflows locally for testing purposes helps conserve these minutes for actual production builds and deployments.

• Offline Development: Develop and test your automation workflows even without an internet connection.

• Debugging: Easily inspect the state of the filesystem, view detailed logs, and debug issues in a familiar local environment.

Introducing act: Your Local GitHub Actions Runner.

To run GitHub Actions locally, you need a tool that can simulate the GitHub runner environment. The most popular open-source tool for this job is act.

act reads your GitHub Actions workflow files and determines the set of actions that need to be executed. It uses Docker to create a secure and isolated container for each operating system specified in your runs-on directives (e.g., ubuntu-latest ). This ensures that your local workflow run mimics the behavior of the actual GitHub-hosted runners as closely as possible.

Step-by-Step Guide: How to Run GitHub Actions Locally with act

Getting started with act is straightforward. Here’s how you can set it up and run your first local GitHub Actions workflow.

Prerequisite: Installing Docker

The main dependency for act is Docker. It utilizes the Docker engine to pull the runner images and execute job steps within containers. Before installing act, ensure that Docker Desktop or Docker Engine is installed and running on your system.

Installing act

You can install act using various package managers depending on your operating system.

• macOS (using Homebrew):

Copy
1
brew install act

• Windows (using Chocolatey or Scoop):

Copy
1
2
3
4
5
# Using Chocolatey
choco install act-cli

# Using Scoop
scoop install act

• Linux (using an installer script):

Copy
1
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Creating a Sample GitHub Actions Workflow

Let's create a new workflow file to test locally. In your project's .github/workflows/ directory, create a new file named local-test.yml with the following code:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
name: Local Test Workflow

on: [pull_request]

jobs:
  local-test-job:
    runs-on: ubuntu-latest
    steps:
      - name: Print a welcome message
        run: echo "This is a test running locally with act!"

      - name: List files in the directory
        run: ls -la

This custom workflow is designed to trigger on a pull request and contains a single job that prints a message and then uses the ls -la command to list files.

Executing the Workflow Locally

Now, navigate to the root directory of your git repository in your terminal and execute act.

1. Run a specific event: Since our workflow is configured to trigger on a pull request, we'll instruct act to simulate that event.

Copy
1
act pull_request

The first time you run act, it will prompt you to select a default Docker image size. The medium size is a good starting point. act will then pull the necessary Docker image for ubuntu-latest and execute the steps defined in local-test-job. You'll see the output from your echo and ls commands directly in your terminal log.

2. List available jobs: To see which jobs will run for a given event, you can use the -l flag.

Copy
1
act -l

This command displays a table of all jobs found in your workflow files that would be triggered by the default (push) event.

3. Run a specific job: If you have a complex GitHub Actions workflow with many jobs, you should test just one. You can do this with the -j flag.

Copy
1
act pull_request -j local-test-job

This command isolates the workflow run to only the local-test-job, ignoring any other jobs in the file. This granularity is a powerful part of the local test process.

Is GitHub Actions Better Than Jenkins?

This is a frequent question for teams evaluating their CI/CD tools. There's no single "better" tool; the right choice depends on your project's needs and context.

GitHub Actions excels in its tight integration with the GitHub platform. If your code lives on GitHub, using GitHub Actions for your CI/CD pipeline feels natural and requires less setup. It's an excellent choice for new projects, open-source development, and teams that prefer a managed solution.

Jenkins, on the other hand, is a highly powerful and extensible automation server. It offers unparalleled control and customization but comes with the responsibility of managing the server and its dependencies. It's a strong contender for organizations with complex, pre-existing pipelines or strict on-premises requirements.

Finalizing Your Workflow: From Local to Live

After thoroughly testing your workflows locally with act, you can be confident that they will function as expected when pushed to your GitHub repository. The local development cycle ensures that your syntax is correct, your commands work, and your logic is sound before you ever commit the changes.

This practice of local validation is a hallmark of an efficient and modern developer workflow. By leveraging tools like act, you can maximize the benefits of GitHub Actions' powerful automation, transforming it from a simple CI/CD tool into a core part of your development process.

Key Takeaways and Next Steps

You've now learned what GitHub Actions are, their core components, and why they are a powerful tool for any developer on GitHub. Most importantly, you know how to break free from the slow cloud-based feedback loop by running your GitHub Actions workflows locally using Act.

• Here's what you can do next:

  ◦ Experiment with act: Install act and try running the existing workflows in one of your projects.

  ◦ Explore Advanced Features: Investigate more complex workflow features, such as matrix builds, secret handling, and job dependencies.

  ◦ Browse the GitHub Marketplace: Discover pre-built actions that can further automate your development tasks and reduce the amount of custom scripting you need to write.

  ◦ Create Workflows: Start building your own GitHub Actions workflow to automate a part of your development process, whether it's for continuous integration or another repetitive task.