How to Specify a Custom Event Path with `act --eventpath`

The act --eventpath flag (short form -e) allows you to inject a custom GitHub event JSON payload into local workflow runs by loading the contents of any file you specify.

When testing GitHub Actions workflows locally with the nektos/act CLI tool, you often need to simulate specific webhook payloads—such as push, pull_request, or release events. By default, act uses an empty JSON object or synthesizes minimal data, but the --eventpath parameter overrides this behavior and supplies your own event context to the runner.

How --eventpath Works Under the Hood

The flag is implemented across three core layers of the codebase: CLI argument parsing, path resolution, and runner configuration.

CLI Flag Registration in cmd/root.go

The flag is defined in the command-line interface using Cobra. In cmd/root.go at line 88, the tool registers --eventpath and binds it to the Input struct:

rootCmd.Flags().StringVarP(&input.eventPath, "eventpath", "e", "", "path to event JSON file")

Source: cmd/root.go

Path Resolution in cmd/input.go

Before the runner executes, the Input struct resolves the user-supplied path. The EventPath() method (lines 108–111) normalizes relative paths against the current working directory while preserving absolute paths unchanged:

func (i *Input) EventPath() string {
    return i.resolve(i.eventPath)
}

Source: cmd/input.go‑L111)

Payload Injection in pkg/runner/runner.go

When the Runner initializes, it checks Config.EventPath. If the field is non-empty, the runner reads the file and stores its contents in runner.eventJSON, which is then mounted as /github/workflow/event.json inside every job container:

if runner.config.EventPath != "" {
    log.Debugf("Reading event.json from %s", runner.config.EventPath)
    eventJSONBytes, err := os.ReadFile(runner.config.EventPath)
    // ...
    runner.eventJSON = string(eventJSONBytes)
}

Source: pkg/runner/runner.go‑L108)

Practical Usage Examples

Creating a Custom Event File

First, define the JSON payload you want to simulate. For example, my-event.json representing a push event:

{
  "ref": "refs/heads/main",
  "head_commit": {
    "id": "a1b2c3d4",
    "message": "Test commit"
  },
  "repository": {
    "full_name": "octocat/hello-world"
  }
}

Running with a Relative Path

Execute act from the repository root, pointing to your custom event:

act -W .github/workflows/build.yml --eventpath my-event.json

The resolver in cmd/input.go joins this relative path with the current working directory before passing it to the runner.

Running with an Absolute Path

You can also reference event files stored anywhere on your filesystem:

act --eventpath /home/user/events/pull_request.json

Because the path begins with /, the resolve() method treats it as absolute and passes it directly to os.ReadFile() without modification.

Combining with Other Flags

--eventpath works alongside other act options such as platform overrides and secrets:

act -e custom-event.json -P ubuntu-20.04=nektos/act-environments-ubuntu:20.04 --secret GITHUB_TOKEN=xyz

This command runs the workflow with your custom payload on a specific container image while injecting repository secrets.

Summary

• --eventpath (or -e) loads a JSON file and uses it as the GitHub event payload for all workflow jobs.
• The flag is registered in cmd/root.go, resolved in cmd/input.go, and consumed in pkg/runner/runner.go.
• Relative paths are resolved against the working directory; absolute paths are passed unchanged.
• If omitted, act defaults to an empty {} object or synthesizes a minimal event containing only the inputs you provide via --input.

Frequently Asked Questions

What happens if I omit --eventpath?

When you do not specify --eventpath, act falls back to an empty JSON object {}. If you provide values via the --input flag, act instead synthesizes a minimal event.json containing only those inputs under the inputs key, which is useful for workflow_dispatch triggers.

Can I use --eventpath to simulate a pull_request event?

Yes. Create a JSON file containing the full pull_request webhook payload structure—including fields like pull_request.number, pull_request.head, and pull_request.base—then run act -e pr-event.json pull_request. The runner will treat the data exactly as if it came from GitHub’s webhook delivery.

What is the difference between --eventpath and --input?

--eventpath supplies the entire raw JSON payload that appears as github.event in your workflow expressions, which is essential for context-specific fields like github.event.head_commit.message. --input only populates the inputs object within a workflow_dispatch or repository_dispatch event, making it suitable for parameterized manual runs but insufficient for testing event-specific logic.

Where does act look for the event.json file by default?

act does not search a default filesystem location for event.json. Unless you explicitly provide --eventpath, the tool generates the payload in memory. When you do provide the flag, the path resolution logic in cmd/input.go checks whether the string is absolute; if not, it prepends the current working directory to locate the file.

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