Claude Code for Act Local GitHub Actions Workflow

If you’ve ever wished you could test your GitHub Actions workflows without pushing code to the remote repository, Act is the tool you need. Act allows you to run your GitHub Actions workflows locally in Docker containers, giving you instant feedback on whether your CI/CD pipeline works correctly before merging any changes. When combined with Claude Code, you get a powerful local development environment for debugging, optimizing, and maintaining your GitHub Actions workflows.

What is Act and Why Use It?

Act is a CLI tool that executes your GitHub Actions workflow files locally using Docker. Instead of pushing to your repository and waiting for GitHub’s CI to run, you can test your entire pipeline on your local machine in seconds or minutes, depending on your workflow complexity.

Benefits of using Act:

Fast iteration – No more waiting for remote CI to complete
Debug locally – Inspect logs and outputs without flooding your CI history
Test secrets – Use local environment variables instead of GitHub secrets
Offline development – Work on your workflows without an internet connection
Cost savings – Reduce CI minutes consumed on GitHub

Installing Act

Before integrating with Claude Code, you’ll need to install Act. The installation process depends on your operating system.

macOS Installation

# Using Homebrew
brew install act

# Or using curl
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Linux Installation

# Using apt
sudo apt install act

# Or using the install script
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Windows Installation

# Using winget
winget install act

# Or using Chocolatey
choco install act

After installation, verify that Act is working:

act --version

Setting Up Act with Your Project

Once Act is installed, navigate to your project repository that contains GitHub Actions workflows:

cd your-project-directory

Act automatically detects workflow files in the .github/workflows/ directory. To see available workflows:

act -l

This command lists all the workflows Act found, making it easy to identify which ones you want to run locally.

Running GitHub Actions Locally with Act

The basic command to run a workflow is straightforward:

# Run the default workflow
act

# Run a specific workflow by name
act -W workflow-name

# Run a specific job
act -j job-name

Using Secrets and Variables Locally

When running locally, Act needs access to secrets and environment variables. There are several ways to provide them:

Option 1: Environment Variables

export MY_SECRET="your-secret-value"
act

Option 2: Secrets File

Create a .secrets file in your project root (add it to .gitignore):

# .secrets file format
MY_SECRET=your-secret-value
ANOTHER_SECRET=another-value

Option 3: Inline Secrets

act --secret MY_SECRET=your-secret-value

Integrating Act with Claude Code

This is where the real power emerges. Claude Code can help you create, debug, and optimize your GitHub Actions workflows by understanding your project’s context and generating appropriate workflow configurations.

Using Claude Code to Generate Workflows

When you need a new GitHub Actions workflow, ask Claude Code to create one based on your project requirements:

“Create a GitHub Actions workflow for a Node.js project that runs tests on Node 18 and 20, lints with ESLint, and deploys to AWS Elastic Beanstalk on the main branch.”

Claude Code will generate a complete workflow file like this:

name: Node.js CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run linter
        run: npm run lint
      
      - name: Run tests
        run: npm test

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy to EB
        uses: einaregilsson/beanstalk-deploy@v20
        with:
          aws_access_key: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws_secret_key: ${{ secrets.AWS_SECRET_KEY }}
          application_name: my-app
          environment_name: my-app-prod
          version_label: ${{ github.sha }}
          region: us-west-2

Debugging Failed Workflows with Claude Code

When Act runs a workflow and something fails, you can paste the error output to Claude Code for analysis:

“This GitHub Actions workflow failed with the error: ‘Error: Cannot find module ‘@actions/core’’. How do I fix this?”

Claude Code will provide specific troubleshooting steps, which might include:

Adding npm install before running Node.js actions
Using actions/cache to cache node_modules
Checking if the action version is correct

Optimizing Your Workflows

Ask Claude Code to review and optimize your existing workflows:

“Review my GitHub Actions workflow and suggest improvements for faster execution and lower costs.”

Claude Code might suggest:

Adding caching for dependencies (npm, pip, etc.)
Running jobs in parallel using a matrix strategy
Using smaller runner images
Skipping unnecessary steps on certain branches

Practical Example: Complete Workflow Development Cycle

Let’s walk through a complete development cycle using Act and Claude Code:

Step 1: Define Your Requirements

Start by explaining your CI/CD needs to Claude Code:

“I need a workflow that builds a Docker image, runs unit tests inside the container, and pushes the image to Docker Hub on every push to main.”

Step 2: Generate the Workflow

Claude Code generates:

name: Docker Build and Push

on:
  push:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .
      
      - name: Run tests
        run: docker run myapp:${{ github.sha }} npm test

  push:
    needs: build-and-test
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Push to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: myapp:latest,myapp:${{ github.sha }}

Step 3: Test Locally with Act

Run the workflow locally:

# Run with dry-run to validate syntax first
act -n

# Run the actual workflow
act

Step 4: Debug with Claude Code

If tests fail or Docker build errors occur, copy the error output and ask Claude Code:

“The Docker build is failing with ‘COPY failed: file not found in build context’. Here’s the error: [paste error]”

Claude Code will identify issues like incorrect paths in Dockerfile or missing files in the build context.

Advanced Act Features

Using Custom Act Configuration

Create a .actrc file in your project root to customize Act’s behavior:

# .actrc
--platform ubuntu-latest=ghcr.io/catthehacker/ubuntu:full-latest
--no-cache
--secret-file .secrets

Running Specific Matrix Combinations

# Run only Node.js 20 on macOS
act -j test --matrix node-version:20

Using Act with GitHub Enterprise

For enterprise users, configure the GitHub instance:

act --hostname github.mycompany.com

Best Practices for Local CI/CD Development

Always test locally first – Use Act before every pull request
Keep secrets local – Never commit real secrets; use .secrets file with .gitignore
Use Act’s dry-run mode – Validate workflow syntax without execution:
```
act -n
```
Cache dependencies – Configure caching in Act to speed up subsequent runs
Leverage Claude Code – Use Claude Code for workflow generation, debugging, and optimization

Conclusion

Act transforms how you develop and test GitHub Actions workflows. By running CI/CD pipelines locally, you get faster feedback, easier debugging, and reduced costs. Combined with Claude Code’s ability to generate, analyze, and optimize your workflows, you have a complete local development environment for modern DevOps practices.

Start integrating Act into your workflow today—your future self will thank you when you’re not waiting for CI builds to complete before discovering a configuration error.

Built by theluckystrike — More at zovo.one