# Hooks

> Scripts of your own that Pullfrog runs before the agent starts, after each checkout, and before each push.

A hook is a script of yours that Pullfrog runs at a fixed point in a run.

| Hook | When it runs | CLI key |
| --- | --- | --- |
| Repo setup script | Once, before the agent starts | `hooks.setup` |
| Post-checkout script | After every branch checkout, the first one included | `hooks.post-checkout` |
| Pre-push script | Before a push | `hooks.pre-push` |

Set hooks in the repository console under **Agent → Hooks**, or with the [CLI](https://pullfrog.com/docs/cli):

```bash
pullfrog config set hooks.setup 'pnpm install --frozen-lockfile'
pullfrog config set hooks.pre-push 'pnpm lint && pnpm test'

# or read a longer script from a file
pullfrog config set hooks.setup --file setup.sh
```

On the default `ubuntu-latest` runner, git, Node.js, npm, pnpm, Python, and Docker are [preinstalled](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md).

## Failed pushes

When the pre-push script fails, the agent gets its output and can fix the problem. Later pushes in the same run skip the hook.

## Environment

Hooks get the same environment and the same sandbox as the agent's [shell commands](https://pullfrog.com/docs/security#shell-environment-scrubbing). You write the scripts, but the code they call is not always yours: on a pull request from a fork, a pre-push script of `pnpm test` runs the contributor's tests.

- A script that needs a secret needs that variable in the [environment allowlist](https://pullfrog.com/docs/security#environment-allowlist), or shell isolation turned off. A missing variable is the usual reason a working script starts to fail.
- On a runner that cannot provide namespace isolation, Pullfrog skips the script instead of running it unprotected. The run continues, and the agent is told the script did not run.
