GitHub Actions Development with act

GitHub Actions have become the go-to automation tool for CI/CD workflows. But there’s a catch: debugging them can feel like shooting in the dark. You commit, push, wait, and hope it works. That’s where act shines.

act brings GitHub Actions to your local machine. It lets you test and iterate on workflows without ever leaving your terminal or pushing to GitHub. In this guide, we’ll walk through how to get started with act using a TypeScript project that installs dependencies, runs a linter, executes tests, and builds a Docker image.

We’ll use the example project from this article: TypeScript Linting

Why Use act?

When developing CI workflows, the delay between writing and testing can slow you down. act solves this by allowing you to:

• Run GitHub Actions locally
• Catch errors before pushing
• Rapidly iterate on workflow logic
• Debug issues in real time

It’s like having a dry-run button for your CI system.

Step 1: Install act

You can install act with Homebrew (macOS/Linux):

brew install act

Or via Docker:

alias act="docker run --rm -it -v $(pwd):/github/workspace -e GITHUB_TOKEN=ghp_xxx nektos/act"

Check the version:

act --version

Step 2: Clone the Example Project (optional)

If you don't have an existing project, then grab my the pre-configured TypeScript project from Typescript Linting:

git clone https://github.com/markcallen/typescript-linting-example.git
cd typescript-linting-example

This project includes:

• ESLint setup for code linting

Step 3: Create the GitHub Actions Workflow

Inside your project root, create the workflow directory:

mkdir -p .github/workflows

Create a file named .github/workflows/ci.yml:

name: CI

on: [push, pull_request]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22.x

      - name: Install yarn
        run: npm install -g yarn

      - name: Install Node.js dependencies
        run: yarn --frozen-lockfile

      - name: Run linters
        run: yarn lint

This workflow:

• Checks out the repo
• Sets up Node.js and yarn
• Installs dependencies
• Runs linting

Step 4: Run Your Workflow with act

To simulate a push event:

act push

You’ll see each step execute in your terminal—no waiting on GitHub.

Need more verbose logs?

act push --verbose

To run a specific job:

act -j build

Want to use a medium-sized Docker image (includes Docker, Node, etc.)?

act --container-architecture linux/amd64 -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest

Tip: You may need Docker running locally for the image build step.

Step 5: Troubleshooting with act

Some common hiccups:

• Missing Docker Socket: Mount it with -v /var/run/docker.sock:/var/run/docker.sock
• Permissions Errors: Use sudo or ensure the current user has access to the Docker group
• Missing Events: act only supports a limited set of triggers (push, pull_request, workflow_dispatch)

Bonus: Local Iteration Workflow

You can quickly iterate on workflow logic like this:

1. Edit .github/workflows/ci.yml
2. Run act push
3. Fix issues in real time
4. Commit once it's green

No more waiting on GitHub runners.

Wrap Up

GitHub Actions are powerful, but act makes them developer-friendly. Whether you're linting TypeScript, testing your app, or building Docker images, act gives you tight feedback loops and fewer broken pipelines.

Start using act today and give your CI a local upgrade.