Brainforge Knowledge

act-setup

3 min read

act Setup - Local GitHub Actions Testing

act lets you run GitHub Actions locally, providing fast feedback without pushing commits or waiting for GitHub-hosted runners.

Prerequisites

  • Docker installed and running (act uses containers to run workflows)
    • On macOS: docker --version should return the version
    • If Docker isn’t running, you’ll see: “Cannot connect to the Docker daemon”

Why Use act?

  • Fast iteration - Test workflow changes in seconds, not minutes
  • No commit noise - Fix issues before pushing to GitHub
  • Cost savings - No GitHub Actions minutes consumed during testing
  • Secrets safety - Test with real credentials locally without exposing them in GitHub logs

Installation

macOS (Homebrew)

brew install act

Other Platforms

See nektos/act releases for binaries or install via:

# GitHub CLI extension
gh extension install nektos/gh-act
 
# Or use the install script
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Configuration

1. Copy secrets template

cp .secrets.example .secrets

Edit .secrets and add your actual tokens:

GITHUB_TOKEN=ghp_your_personal_access_token
SLACK_BOT_TOKEN=xoxb_your_slack_bot_token

Get your tokens:

  • GitHub Token: github.com/settings/tokens - needs repo and workflow scopes
  • Slack Bot Token: From 1Password (Brainforge AI Team vault) or Slack app settings

2. Review .actrc (optional)

The repo includes a .actrc file with sensible defaults:

-P ubuntu-latest=catthehacker/ubuntu:act-latest
--secret-file .secrets
--rm

Basic Usage

List available workflows

act -l

Run a specific workflow

# Run workflow_dispatch event for daily-platform-summary
act workflow_dispatch -W .github/workflows/daily-platform-summary.yml
 
# Run a specific job
act workflow_dispatch -j post-summary

Run with specific secrets

act workflow_dispatch -j post-summary --secret-file .secrets

Dry run (see what would execute)

act -n workflow_dispatch

Verbose output

act -v workflow_dispatch

Testing the Daily Platform Summary Workflow

Prerequisites

  1. Ensure .secrets has valid tokens:

    • GITHUB_TOKEN - for fetching merged PRs
    • SLACK_BOT_TOKEN - for posting to Slack

  2. The workflow uses ubuntu-latest which maps to catthehacker/ubuntu:act-latest (pre-installed with curl, jq, etc.)

Run the test

act workflow_dispatch -j post-summary

Expected behavior

  • Workflow fetches PRs merged in last 24h from GitHub API
  • Constructs Slack message payload using jq
  • Posts to #platform channel (C08CRQJ636X)
  • Prints success or error message

Common issues

IssueSolution
jq: command not foundUse -P ubuntu-latest=catthehacker/ubuntu:act-latest
SLACK_BOT_TOKEN not setEnsure .secrets file exists and has the token
channel_not_foundBot not in channel - invite it in Slack
invalid_argumentsMalformed JSON - check jq syntax in workflow

Pro Tips

Test without posting to Slack

Temporarily change the curl command in the workflow to echo instead of POST:

echo "$SLACK_PAYLOAD" | jq .

Test specific PR scenarios

Modify the SINCE_TIMESTAMP calculation to look at a specific date range:

# Look at last 7 days instead of 24h
SINCE_TIMESTAMP=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)

Debug jq issues

Add set -x to the workflow run script for verbose shell output.

CI/CD Integration

Consider adding an act step to your pre-commit hooks or local CI script:

#!/bin/bash
# test-workflows.sh
 
echo "Testing GitHub Actions locally..."
act workflow_dispatch -j post-summary -q || exit 1

Graph View