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 like staging or dev.
  • 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:

image

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.