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

> Learn to specify a custom event path with act --eventpath and inject your own GitHub event JSON payloads for local workflow runs. Easily control your tests.

- Repository: [nektos/act](https://github.com/nektos/act)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/nektos/act/blob/main/cmd/root.go)

The flag is defined in the command-line interface using Cobra. In [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) at line 88, the tool registers `--eventpath` and binds it to the `Input` struct:

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

```

*Source: [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go#L88)*

### Path Resolution in [`cmd/input.go`](https://github.com/nektos/act/blob/main/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:

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

```

*Source: [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go#L108)‑L111)*

### Payload Injection in [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main//github/workflow/event.json) inside every job container:

```go
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`](https://github.com/nektos/act/blob/main/pkg/runner/runner.go#L99)‑L108)*

## Practical Usage Examples

### Creating a Custom Event File

First, define the JSON payload you want to simulate. For example, [`my-event.json`](https://github.com/nektos/act/blob/main/my-event.json) representing a `push` event:

```json
{
  "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:

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

```

The resolver in [`cmd/input.go`](https://github.com/nektos/act/blob/main/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:

```bash
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:

```bash
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`](https://github.com/nektos/act/blob/main/cmd/root.go), resolved in [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go), and consumed in [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/event.json) file by default?

`act` does not search a default filesystem location for [`event.json`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/cmd/input.go) checks whether the string is absolute; if not, it prepends the current working directory to locate the file.