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

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:

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), 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 (lines 73-94):

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

} 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:

# 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:

# 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:

# 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:

# 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: 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: 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: 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 aggregates all triggers into a sorted, deduplicated list before selection occurs.
• 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, 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.

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