How to Force Rebuild Docker Images in act: Complete Guide

Use the --rebuild flag to force act to rebuild Docker images for local actions, or set --rebuild=false to reuse cached images and skip unnecessary builds.

The nektos/act CLI tool executes GitHub Actions workflows locally using Docker containers. When you need to force rebuild Docker images in act—such as after modifying a local action's Dockerfile or source code—you must understand how the tool handles image caching to ensure your changes take effect.

Understanding the --rebuild Flag

By default, act rebuilds Docker images for local actions on every run. The --rebuild boolean flag in cmd/root.go defaults to true, meaning the tool automatically discards cached images and rebuilds them unless you explicitly disable this behavior. To reuse existing images and speed up execution, you must pass --rebuild=false.

This design ensures that local action changes are always picked up during development, while CI environments or repetitive testing can opt into caching for performance.

How Force Rebuild Works Under the Hood

The rebuild logic flows through several components in the nektos/act codebase, from CLI parsing to Docker execution.

CLI Flag Definition

In cmd/root.go at line 86, the --rebuild flag is defined as a Boolean with a default value of true:

// Simplified representation of the flag definition
cmd.PersistentFlags().BoolP("rebuild", "", true, "rebuild local action docker images")

This means the flag is effectively always present, defaulting to forced rebuild behavior when omitted from the command line.

Runner Configuration Propagation

The flag value propagates through the input struct and into RunnerConfig at line 612 of cmd/root.go, specifically mapping to the ForceRebuild field:

// Configuration mapping
runnerConfig.ForceRebuild = input.rebuild

The RunnerConfig struct in pkg/runner/runner.go at line 33 stores this setting, making it available to the execution engine.

Image Rebuild Decision Logic

When act prepares to execute a Docker-based local action, pkg/runner/action.go at line 287 evaluates whether to rebuild. The code checks two conditions: whether the required architecture is already present in the cache, or whether ForceRebuild is true. If either condition is met, act triggers a rebuild:

// Conceptual representation of the check
if needsRebuild || rc.Config.ForceRebuild {
    // Proceed to docker build
}

Docker Build Execution

The actual rebuild occurs in pkg/runner/step_docker.go, which invokes the Docker daemon with the appropriate docker build command. This step only uses the cached image context when ForceRebuild is explicitly set to false.

Practical Usage Examples

Forcing a Fresh Build

To ensure all local action images are rebuilt with your latest changes, run act with the default rebuild behavior:

act --rebuild

Since the flag defaults to true, you can also simply run act without arguments to achieve the same result.

Reusing Cached Images

To skip rebuilding and use existing Docker images for faster execution:

act --rebuild=false

This is useful when running workflows repeatedly without modifying local actions.

Integration with CI Scripts

Add the flag to shell scripts or Makefiles for consistent behavior across environments:

#!/usr/bin/env bash

# Force fresh builds in CI environment

act --rebuild --job test

Or in a Makefile:

.PHONY: local-ci
local-ci:
	act --rebuild=false --job build

Summary

• Default behavior: Act rebuilds Docker images on every run (--rebuild defaults to true).
• Disable rebuilds: Use --rebuild=false to cache and reuse local action images.
• Source flow: The flag travels from cmd/root.go → RunnerConfig.ForceRebuild in pkg/runner/runner.go → rebuild logic in pkg/runner/action.go → execution in pkg/runner/step_docker.go.
• Rebuild trigger: Occurs when ForceRebuild is true or when the required architecture is missing from the cache.

Frequently Asked Questions

What is the default value of the --rebuild flag in act?

The --rebuild flag defaults to true as defined in cmd/root.go. This means act automatically rebuilds Docker images for local actions on every run unless you explicitly pass --rebuild=false.

How do I skip Docker image rebuilding to speed up local testing?

Pass --rebuild=false to the act command. This tells the runner to reuse any existing cached images for local actions, significantly reducing execution time when you have not modified the action code or Dockerfile.

Does --rebuild affect remote actions or only local actions?

The --rebuild flag specifically controls Docker image building for local actions (actions defined in your repository). Remote actions pulled from external repositories are not affected by this flag, as they use pre-built images or their own build processes.

Where is the force rebuild logic implemented in the act source code?

The logic spans four key files: cmd/root.go defines the flag and passes it to the runner; pkg/runner/runner.go stores it in RunnerConfig.ForceRebuild; pkg/runner/action.go at line 287 checks the flag to decide whether to rebuild; and pkg/runner/step_docker.go executes the actual Docker build command.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}