Setting the Default Branch in act with the `--defaultbranch` Flag

The --defaultbranch flag tells act which branch name to use as the repository default, ensuring ${{ github.ref }} resolves correctly in local GitHub Actions runs.

When running GitHub Actions locally with nektos/act, workflows often reference the repository's default branch through ${{ github.ref }} or ${{ github.base_ref }}. Setting the default branch in act ensures that push events and pull requests behave consistently with your actual repository configuration, preventing unexpected "master" fallbacks during execution.

How the Flag Propagates Through the Codebase

The --defaultbranch value flows from command-line parsing through the runner configuration and finally into the GitHub context. Understanding this path helps debug why workflows might reference the wrong branch.

CLI Definition in cmd/root.go

The flag is defined in cmd/root.go at line 89, where it binds to the input struct:

rootCmd.Flags().StringVar(&input.defaultBranch, "defaultbranch", "", "the name of the main branch")

This captures the user input and defaults to an empty string if omitted.

Runner Configuration Assembly

After parsing, the value is injected into the runner configuration at line 610 of cmd/root.go:

Config: runner.Config{
    DefaultBranch: defaultbranch,
    …
}

The runner.Config struct—defined around line 30 in pkg/runner/runner.go—stores this value for the duration of the execution.

Runtime Context Injection in run_context.go

During job execution, pkg/runner/run_context.go applies the configured branch to the GitHub context. At line 952, the code calls:

ghc.SetRef(ctx, rc.Config.DefaultBranch, repoPath)

This ensures that any workflow step referencing ${{ github.ref }} receives the branch name supplied via the flag.

GitHub Context Enrichment in github_context.go

The pkg/model/github_context.go file handles edge cases where the event payload lacks branch information. The helper function withDefaultBranch (line 71) injects the default branch into github.ref when missing. If --defaultbranch is omitted, the code falls back to "master" at lines 131‑133:

if ref == "" {
    ref = "refs/heads/master"
}

Practical Usage Examples

Run a workflow assuming your repository uses "main" as the default branch:

act --defaultbranch main

Target a specific workflow file while overriding the default branch:

act -W .github/workflows/build.yml --defaultbranch develop

To verify that act honors the flag, add a debug step to your workflow:

steps:
  - name: Show default branch
    run: echo "Default branch is ${{ github.ref }}"

Running with act --defaultbranch release outputs:

Default branch is refs/heads/release

Summary

• Command-line entry: The flag is defined in cmd/root.go (line 89) and stored in the input struct.
• Configuration propagation: cmd/root.go (line 610) passes the value to runner.Config.DefaultBranch.
• Context application: pkg/runner/run_context.go (line 952) sets the reference via ghc.SetRef.
• Fallback behavior: If omitted, pkg/model/github_context.go (lines 131‑133) defaults to "master".

Frequently Asked Questions

What happens if I omit the --defaultbranch flag?

If you do not provide the flag, act defaults to "master" as the repository's main branch. According to pkg/model/github_context.go lines 131‑133, the code explicitly falls back to "refs/heads/master" when no default branch is configured.

Does --defaultbranch affect all workflow event types?

The flag affects any workflow that queries ${{ github.ref }}, including push, pull_request, and scheduled events. The withDefaultBranch helper in pkg/model/github_context.go ensures the branch is injected whenever the event payload lacks explicit reference data.

How can I confirm which branch act is using at runtime?

Add a step that prints ${{ github.ref }} to standard output. When running locally, compare the output against the value you passed to --defaultbranch. If they match, the flag propagated correctly through run_context.go and github_context.go.

Can I set the default branch via environment variable instead of a flag?

Based on the current implementation in nektos/act, the default branch must be specified via the --defaultbranch CLI flag. The codebase binds the value directly from cobra flag parsing in cmd/root.go without checking for a corresponding environment variable.

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