How to Test GitHub Actions Locally Using act
Today, I wanted to experiment with GitHub Actions locally before committing to the repository. I came across a cool tool called act
, which allows you to run GitHub Actions workflows on your local machine. It's perfect for catching setup and script errors early and avoiding unnecessary commits just to trigger CI runs.
What is act?
act
is an open-source CLI tool that emulates the GitHub Actions environment locally using Docker containers. This makes it incredibly easy to test workflows without pushing code to GitHub.
Setting Up GitHub Actions Workflow
I wanted to create a workflow to automatically build static assets with Eleventy and deploy them to Cloudflare Pages. Later, I'd also like to include syncing information to a vector database, but one step at a time!
Prerequisites
First, you need an environment in your GitHub repository with necessary secrets like CLOUDFLARE_ACCOUNT_ID
and CLOUDFLARE_API_TOKEN
. Here's how you can set these up:
- Go to your repository settings and create a new environment named
production
or anything else meaningful likestaging
ordev
. - Get your secrets from Cloudflare's API Tokens page using the "Edit Cloudflare Workers" template.
- Add these secrets (
CLOUDFLARE_ACCOUNT_ID
,CLOUDFLARE_API_TOKEN
) to your GitHub environment.
Workflow YAML (deploy.yml
)
Here’s my GitHub Actions workflow configuration:
name: Build and Deploy Static Site to Cloudflare Pages
on:
push:
branches:
- main
workflow_dispatch:
jobs:
build_and_deploy_static:
name: Build and Deploy Static Content
environment: production # whatever you named your Github environment
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Setup PNPM
uses: pnpm/action-setup@v3
with:
version: 10.10.0
- name: Setup Node.js (from .nvmrc)
uses: actions/setup-node@v4
with:
node-version-file: ".nvmrc"
cache: "pnpm"
- name: Install Dependencies
run: pnpm install --frozen-lockfile
- name: Build 11ty Site
env:
ELEVENTY_RUN_MODE: "build"
NODE_ENV: production
run: pnpm run build
- name: Deploy to Cloudflare Pages
if: github.repository_owner == 'abpai'
uses: cloudflare/wrangler-action@v3
with:
apiToken: $
accountId: $
command: pages deploy _site --project-name=til --branch=main
At first, I setup an environment called deployment
and added the secrets to that environment and received the following error:
I had to add the secrets to the production
environment instead and specify that environment in the workflow YAML file.
Using act for Local Testing
Installation
Install act
easily via Homebrew:
brew install act
Running act Locally
To test your workflow locally, navigate to your repository directory and run:
act
By default, act runs in a medium-sized Docker container which simulates GitHub's environment closely. If you need environment-specific secrets, you can use a .env
file or pass them directly via the command line:
act -s CLOUDFLARE_API_TOKEN=mytoken -s CLOUDFLARE_ACCOUNT_ID=myaccountid
This command runs your workflow locally, allowing you to debug any issues directly from your terminal.
Common Issues
If you encounter errors related to missing secrets or Docker issues:
- Ensure Docker is running on your machine.
- Verify your
.env
file or command line secrets are correctly provided. - Double-check your workflow YAML for syntax errors.