Configuring Action Inputs for Local Runs with act --input

Use the --input key=value flag or --input-file to pass values to ${{ inputs.* }} expressions when running GitHub Actions locally with act.

When testing GitHub Actions workflows locally using the open-source tool act, supplying values for action inputs requires specific CLI configuration. The nektos/act repository provides the --input and --input-file flags to inject these variables into your local runner environment, enabling full emulation of workflow inputs without pushing to GitHub.

How the --input Flag Is Defined

The command-line interface declares the input flag in cmd/root.go at lines 78–82, where Cobra binds the flag to the Input struct:

rootCmd.Flags().StringArrayVarP(&input.inputs, "input", "", []string{}, "action input to make available to actions (e.g. --input myinput=foo)")

The Input struct, defined in cmd/input.go (lines 9–22), stores the raw values in a string slice:

type Input struct {
    inputs []string
    // ... other fields
}

This struct also provides helper methods such as Envfile(), Secretfile(), Varfile(), and Inputfile() (lines 13–17) to resolve file-path flags relative to the working directory.

Data Flow from CLI to Workflow

Understanding how act processes inputs helps debug configuration issues. The flow follows three distinct stages:

1. Flag Parsing – Cobra stores each --input key=value occurrence in input.inputs as a raw string.
2. Resolution – The Input.resolve method (lines 70–81 of cmd/input.go) converts relative file paths to absolute ones. Note that this resolution applies only to file-path flags, not to the plain key/value pairs passed via --input.
3. Runner Injection – In pkg/runner/action.go, the runner constructs a github.ActionsInput map by splitting each slice element on the = character. This map is injected into the action's environment, making values accessible via ${{ inputs.<name> }}.

Practical Usage Patterns

Single and Multiple Inputs

Provide individual inputs using repeated --input flags:

# Single input

act -j build --input version=1.2.3

# Multiple inputs

act -j test --input env=staging --input debug=true --input region=eu-west-1

File-Based Inputs with --input-file

For complex configurations, store inputs in a file and reference them with --input-file. The file must contain one key=value pair per line:

cat > .inputs <<'EOF'
version=1.2.3
debug=true
env=production
EOF

act -j deploy --input-file .inputs

Important: act does not automatically read an .input file; you must explicitly specify the file path using --input-file.

Override Behavior

When combining --input-file with inline --input flags, command-line values take precedence. The runner processes the file first, then applies explicit CLI overrides:

act --input-file .inputs --input debug=false  # Overrides debug=true from file

Accessing Inputs Inside Workflows

Once passed to act, inputs are available in workflow expressions using the standard GitHub Actions syntax. The runner injects these values before executing composite or Docker actions.

# .github/workflows/example.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Display inputs
        run: |
          echo "Version: ${{ inputs.version }}"
          echo "Environment: ${{ inputs.env }}"

Running act --input version=1.2.3 --input env=staging will substitute these values into the workflow output.

Key Implementation Files

The end-to-end input handling involves these critical source files:

• cmd/root.go – Declares the --input flag and binds it to the Input.inputs slice.
• cmd/input.go – Defines the Input struct, path resolution logic, and file-handling helpers.
• pkg/runner/action.go – Parses the input slice into a github.ActionsInput map and injects it into the action environment.
• pkg/model/workflow.go – Defines the workflow model that references inputs during expression evaluation.

Summary

• The --input flag accepts key=value pairs to emulate GitHub Actions inputs locally.
• Flag definitions reside in cmd/root.go and state management in cmd/input.go.
• The runner converts inputs into a github.ActionsInput map in pkg/runner/action.go.
• Use --input-file to load inputs from a line-delimited file; act does not auto-detect input files.
• Command-line inputs override values specified in input files.
• Access passed values in workflows via ${{ inputs.<name> }} expressions.

Frequently Asked Questions

Does act automatically read .input files from the repository?

No. Unlike .env or .secrets files, act does not automatically detect or load input files. You must explicitly specify the file path using the --input-file flag. The file must contain one key=value pair per line, which the runner parses and merges with any --input flags provided on the command line.

How do I override specific inputs when using an input file?

Command-line --input flags always take precedence over file-based inputs. The runner processes the --input-file first, then applies any --input flags, allowing you to override specific values without modifying the file. For example: act --input-file .inputs --input debug=false will use all values from .inputs except debug, which becomes false.

Can I use act inputs with composite actions?

Yes. The --input flag works for both standard workflows and composite actions. In pkg/runner/action.go, the runner builds the github.ActionsInput map and injects it into the environment before executing composite or Docker actions, making the values available via ${{ inputs.<name> }} regardless of the action type.

Where does act validate the input syntax?

act performs minimal validation at the CLI level. The cmd/root.go file defines the flag as a string array, accepting any key=value format. Actual parsing and splitting on the = character occur in pkg/runner/action.go when the runner constructs the github.ActionsInput map. Invalid formats may result in empty values rather than immediate errors.

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