Skip to content

CLAUDE.md

Latest commit

 

History

History
63 lines (45 loc) · 2.92 KB

CLAUDE.md

File metadata and controls

63 lines (45 loc) · 2.92 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Act is a tool to run GitHub Actions locally. It reads .github/workflows/ files, builds an execution plan, and uses Docker to run containers for each action. Written in Go 1.24+.

Common Commands

  • make build — build binary to dist/local/act
  • make test — run go test ./... and the act CLI
  • make lint-go — run golangci-lint run
  • make format — run go fmt ./...
  • make tidy — run go mod tidy
  • make pr — full PR checklist: tidy, format-all, lint, test
  • go test ./pkg/runner/... — run tests for a single package
  • go test ./pkg/runner/ -run TestRunEvent — run a single test

Architecture

Execution Flow

  1. CLI (cmd/root.go) — Cobra-based CLI parses flags into an Input struct
  2. Planner (pkg/model/planner.go) — parses workflow YAML into a Plan containing Stages (serial) with Runs (parallel jobs)
  3. Runner (pkg/runner/runner.go) — converts the Plan into composable Executor chains
  4. RunContext (pkg/runner/run_context.go) — holds all state for a job execution (env vars, matrix, containers, expressions)
  5. Steps (pkg/runner/step.go) — each step type (action, docker, script) implements the step interface

Core Abstraction: Executor Pattern

The Executor type (pkg/common/executor.go) is a func(ctx context.Context) error used throughout the codebase. Executors compose via:

  • .Then(), .Finally(), .OnError() — chaining
  • NewPipelineExecutor() — serial execution
  • NewParallelExecutor() — parallel execution
  • .If(), .IfNot() — conditional execution

Key Packages

  • pkg/model/ — workflow YAML parsing, plan creation, action definitions
  • pkg/runner/ — core execution engine, expression evaluation, step types (local/remote/docker/composite actions, reusable workflows)
  • pkg/container/ — Docker API wrapper, container and host execution environments
  • pkg/common/ — Executor pattern, context utilities, logging
  • pkg/exprparser/ — GitHub Actions ${{ }} expression language interpreter
  • pkg/artifacts/ and pkg/artifactcache/ — artifact upload/download and caching server

Linting Rules

Configured in .golangci.yml:

  • Use errors from stdlib, not github.com/pkg/errors
  • Use github.com/sirupsen/logrus (aliased as log), not stdlib log
  • Use github.com/stretchr/testify for tests, not gotest.tools/v3
  • Max cyclomatic complexity: 20
  • Import aliases enforced: logrus → log, testify/assert → assert

Testing

  • Tests use testify/assert and testify/mock
  • Table-driven tests are common in pkg/model/ and pkg/exprparser/
  • Test fixtures live in testdata/ directories alongside their packages
  • pkg/runner/testdata/ contains extensive sample GitHub Actions workflows used as integration test fixtures