# Detecting GitHub Events Automatically with act --detect-event: A Complete Implementation Guide

> Learn how to detect GitHub events automatically with act --detect-event. This guide shows you how to infer triggering events, saving you manual configuration time.

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

---

**The `act --detect-event` flag automatically infers the triggering event from your workflow files, eliminating the need to manually specify events like `push` or `pull_request` on the command line.**

The `nektos/act` CLI tool enables local GitHub Actions execution, but traditionally requires explicit event arguments to simulate triggers. By leveraging the **`--detect-event`** flag, you can automatically detect GitHub events directly from the `on:` sections of your workflow definitions, streamlining local testing without manually typing event names.

## How Automatic Event Detection Works in act

The automatic event detection feature operates through a three-stage pipeline spanning flag capture, event aggregation, and event selection. According to the `nektos/act` source code, this implementation relies on specific components within the command interface and workflow planner.

### Flag Definition in cmd/root.go

The CLI exposes the detection capability through a boolean flag defined at line 87 of [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go):

```go
rootCmd.Flags().BoolVarP(&input.autodetectEvent, "detect-event", "", false,
    "Use first event type from workflow as event that triggered the workflow")

```

This declaration populates the `autodetectEvent` field in the `Input` struct (defined in [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go)), allowing subsequent logic to check whether to bypass manual event specification.

### Event Aggregation in pkg/model/planner.go

Before selection occurs, the system gathers all possible events from the repository's workflows. The `workflowPlanner` struct implements the `GetEvents()` method in [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go) (lines 73-94):

```go
func (wp *workflowPlanner) GetEvents() []string { … }

```

This function walks every parsed workflow file, extracts the `on:` sections, and returns a **sorted, deduplicated list** of event names. If your workflow defines `on: [push, pull_request]`, both events appear in the returned slice, ordered alphabetically.

### Event Selection and Fallback Logic

The actual selection happens in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) during both the planning and execution phases. When `input.autodetectEvent` evaluates to true and valid events exist, the CLI selects the first element from the slice:

```go
} else if input.autodetectEvent && len(events) > 0 && len(events[0]) > 0 {
    eventName = events[0]        // first detected event becomes the trigger
} else {
    eventName = "push"           // fallback default
}

```

The same conditional logic applies when filtering jobs for `--list` or `--graph` operations (lines 90-95). The **first event** returned by `GetEvents()` becomes the implicit trigger, matching the behavior described in the help text.

## Practical Usage Examples for act --detect-event

These examples demonstrate how to integrate automatic event detection into your local development workflow.

### Basic Workflow Execution

Run a workflow without specifying the event manually:

```bash

# Detect the first event from the workflow files and execute it

act --detect-event

```

If the workflow contains `on: [push, pull_request]`, the command behaves exactly as if you ran `act push` (assuming "push" sorts first alphabetically, though "pull_request" would actually come first).

### Integration with Watch Mode

Combine automatic detection with filesystem monitoring:

```bash

# Watch the repository and re-run whenever files change,

# automatically detecting the event each time

act --detect-event --watch

```

### Listing Jobs for Detected Events

Preview which jobs would execute for the automatically selected event:

```bash

# Show the jobs that would run for the first workflow event

act --detect-event --list

```

### Custom Workflow Directories

Point to non-standard workflow locations while still using automatic detection:

```bash

# Point act to a custom workflow directory and let it pick the event

act --detect-event -W ./my-workflows

```

## Core Source Files and Architecture

Understanding the implementation requires familiarity with three specific files in the `nektos/act` repository:

- **[`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go)**: Declares the `--detect-event` flag and implements the conditional logic that assigns either the detected event or the default `"push"` to the `eventName` variable during both planning and execution phases.

- **[`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go)**: Defines the `Input` struct including the `autodetectEvent` boolean field that stores the flag state passed from the CLI parser to the runtime.

- **[`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go)**: Contains the `GetEvents()` function that performs static analysis of parsed workflow files to extract trigger events and return them as a sorted, deduplicated slice.

## Summary

- The **`--detect-event`** flag in `nektos/act` eliminates manual event specification by reading the `on:` sections of workflow files.
- The `GetEvents()` function in [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go) aggregates all triggers into a **sorted, deduplicated list** before selection occurs.
- [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) selects the **first event** from this list when `autodetectEvent` is enabled, falling back to `"push"` if no events are found or the flag is omitted.
- The feature integrates seamlessly with other CLI flags including `--watch`, `--list`, and `-W` for custom workflow directories.

## Frequently Asked Questions

### What happens if my workflow file defines multiple events?

When using `--detect-event`, `act` selects only the **first event** from the alphabetically sorted list returned by `GetEvents()`. For example, if your workflow triggers on `[push, pull_request]`, the command behaves like `act pull_request` (since "pull_request" sorts alphabetically before "push"). You cannot automatically iterate through multiple events with a single command execution.

### Does act --detect-event work with workflow_dispatch or scheduled events?

Yes, the detection logic treats all event types equally during aggregation. If `workflow_dispatch` or `schedule` appears in the `on:` section and happens to be first in the sorted list returned by `GetEvents()`, `act` uses that as the trigger. However, alphabetically `push` and `pull_request` typically appear before `workflow_dispatch` unless no other events are defined.

### Why does act default to the "push" event without the --detect-event flag?

According to the source code in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go), when `autodetectEvent` is false and no explicit event is provided via command-line arguments, the `eventName` variable hardcodes to `"push"`. This maintains backward compatibility with earlier versions of `act` and reflects the most common CI/CD pattern where workflows trigger on code pushes to the repository.

### Can I use --detect-event with specific job filtering or matrix combinations?

Yes, the `--detect-event` flag only determines the triggering event type; it does not conflict with job filtering flags. You can combine it with `-j <job_id>` to run a specific job, or with matrix configuration flags, because event detection happens during the planning phase before job selection and matrix expansion occur.