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

> Easily set the default branch in act with the --defaultbranch flag for accurate local GitHub Actions runs and correct ${{ github.ref }} resolution.

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

---

**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`](https://github.com/nektos/act/blob/main/cmd/root.go) at line 89, where it binds to the `input` struct:

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

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

```

The `runner.Config` struct—defined around line 30 in [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/pkg/runner/run_context.go) applies the configured branch to the GitHub context. At line 952, the code calls:

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

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

```

## Practical Usage Examples

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

```bash
act --defaultbranch main

```

Target a specific workflow file while overriding the default branch:

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

```

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

```yaml
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`](https://github.com/nektos/act/blob/main/cmd/root.go) (line 89) and stored in the `input` struct.
- **Configuration propagation**: [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) (line 610) passes the value to `runner.Config.DefaultBranch`.
- **Context application**: [`pkg/runner/run_context.go`](https://github.com/nektos/act/blob/main/pkg/runner/run_context.go) (line 952) sets the reference via `ghc.SetRef`.
- **Fallback behavior**: If omitted, [`pkg/model/github_context.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/run_context.go) and [`github_context.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/cmd/root.go) without checking for a corresponding environment variable.