Pre-push hooks

The default generated hook runs at pre-push, not pre-commit, because full GitHub Actions workflows are often too slow for every commit.

Create the hook entry during Bellows setup:

1
2bellows init --pre-commit
pre-commit install --hook-type pre-push

Or install the Bellows hook later:

1
2bellows hooks install --stage pre-push
pre-commit install --hook-type pre-push

Generated Hook

Generated config:

1
2
3
4
5
6
7
8
9repos:
  - repo: local
    hooks:
      - id: bellows
        name: Run GitHub Actions locally with Bellows
        entry: bellows run --precommit
        language: system
        pass_filenames: false
        stages: [pre-push]

Hook ID

Use:

1bellows

Stage

Default:

1stages: [pre-push]

Users may opt into pre-commit, but Bellows does not generate that by default.

1bellows hooks install --stage pre-commit

Command Behavior

bellows run --precommit:

• loads .bellows.yml;

• runs configured default workflows through act;

• uses precommit.mode: changed-files when configured;

• preserves the underlying workflow failure exit code;

• prints a concise summary;

• prints the exact command to rerun manually when a failure occurs.

Example failure footer:

1
2Bellows failed while running .github/workflows/ci.yml job test.
Rerun: bellows run --workflow .github/workflows/ci.yml --job test

Manual Installation

Users can add Bellows manually:

1pre-commit install --hook-type pre-push

Then run:

1pre-commit run bellows --hook-stage pre-push

Changed Files Mode

Use changed-files mode to select workflows or jobs from Git changes before a push:

1
2
3
4
5
6
7
8precommit:
  mode: changed-files
  paths:
    - pattern: "docs/*"
      workflows: [docs.yml]
    - pattern: "**/*.go"
      workflows: [ci.yml]
      jobs: [test]

When no changed file matches a rule, bellows run --precommit exits without running Docker.

Patterns support ** for nested monorepo paths.

Debug rule selection without running Docker:

1bellows explain changed-files

Existing Lefthook repositories

Keep Lefthook as your hook manager. Add a named command under the existing pre-push.commands mapping in lefthook.yml; retain the rest of your file, including format and lint hooks. If a bellows command already exists, update that entry instead of adding a duplicate YAML key.

1
2
3
4pre-push:
  commands:
    bellows:
      run: bellows run --precommit

Install Bellows and its runtime dependencies, then initialize its configuration without generating another hook manager's configuration:

1
2
3bellows init
lefthook install
lefthook run pre-push

Run bellows init only when .bellows.yml does not already exist. Review the configuration before enabling the hook. Re-running lefthook install after editing its configuration does not require replacing your existing commands. Do not use bellows hooks install or pre-commit install alongside Lefthook; those instructions above are for repositories using the pre-commit framework.

For a repository whose Flox environment supplies Bellows, act and Docker CLI, replace only the command's run value:

1run: flox activate -- bellows run --precommit

Lefthook starts commands from the repository; no hard-coded checkout path is needed, including when the directory contains spaces. Activate Flox explicitly in the command so Git clients do not depend on an interactive shell activation. Flox itself must be available to the Git client. A running Docker daemon is still required. A failed command makes the pre-push hook fail.

Keep full verification for pre-push unless your changed-file rules are proven to cover the changes being pushed. Local hooks can be bypassed and are developer feedback, not enforced GitHub merge protection. Keep hosted CI and existing repository protections in place when using advisory local verification.