pre-commit cannot fetch hook repos (offline / no cache) in CI

By Kaveh Alemi·Latchkey

pre-commit clones each hook repo into its cache before running. On a runner with restricted egress or no cached PRE_COMMIT_HOME, the clone fails and no hook can run.

What this error means

Env setup fails with a git clone error ("Could not resolve host" or "Connection timed out") while pre-commit is "Installing environment for" a hook repo.

[INFO] Initializing environment for https://github.com/psf/black.
fatal: unable to access 'https://github.com/psf/black/':
Could not resolve host: github.com

Common causes

The runner cannot reach the hook repo host

Restricted egress or a transient DNS failure blocks the clone, so pre-commit cannot fetch the hook repository.

No cached PRE_COMMIT_HOME to fall back on

Without a persisted cache, every run must clone from scratch, so any network hiccup fails the job.

How to fix it

Persist and reuse the cache

1. Cache ~/.cache/pre-commit keyed on the config file.
2. Restore it before running so hook repos are already present.
3. Only cold runs then need the network.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pre-commit
    key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
- run: pre-commit run --all-files

Point PRE_COMMIT_HOME at a prewarmed cache

Set PRE_COMMIT_HOME to a directory you populate once so restricted runners never clone.

export PRE_COMMIT_HOME="$GITHUB_WORKSPACE/.pre-commit-cache"
pre-commit install-hooks

How to prevent it

• Cache PRE_COMMIT_HOME so hook repos are cloned once.
• Prewarm the cache with pre-commit install-hooks on a networked step.
• Allowlist the hook repo hosts on egress-restricted runners.

Frequently asked questions

Related guides

References

• GitHub Actions documentation