> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-cloud-runtime-security/cortex-cli/cortex-cli-for-code-security/cortex-cli-pre-receive-hooks/pre-receive-hook-usage.md).

# Pre-receive hook usage

The hook executes a script on every git push.

By default, Cortex CLI pre-receive hooks:

* **Only scans code changes**: It analyzes the code difference included in the pushed commits, not the entire repository
* **Scans for secrets only**: The analysis is focused on detecting sensitive information
* **Does not upload results to Cortex Cloud**: All scan results are kept local to your machine (on the server)

## Understanding the script variables

* `CORTEX_CLI`: Defines the executable path, pointing to the absolute location of the `cortexcli` binary
* `BASE_COMMAND`: Assembles the core command string, including authentication flags (`--api-base-url`, `--api-key-id`, `--api-key`) and the primary command: `code pre-receive`. The use of `${...}` ensures authentication variables are injected as flag values
* `OPTIONAL_FLAGS`: An empty variable placeholder for adding optional runtime arguments

## Command flag reference

Use the following flags with the pre-receive command to customize scanner behavior.

**Example command structure:**

```programlisting
$ cortexcli code pre-receive [options]
```

| Command                     | Description                                                                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ignore-existing-secrets` | Ignores secrets that already exist in the periodic scan (default: false) `[$CORTEX_CODE_IGNORE_EXISTING_SECRETS]`                                                 |
| `--validate-secrets`        | Checks if the secrets are valid (default: false) `[$CORTEX_CODE_VALIDATE_SECRETS]`                                                                                |
| `--skip-path`               | Specifies a file or directory path to skip during the scan `[$CORTEX_CODE_SKIP_PATH]`                                                                             |
| `--compact`                 | Prevents the display of code blocks in the output (default: false) `[$CORTEX_CODE_COMPACT]`                                                                       |
| `--summary-position`        | Determines whether the summary appears on top (before the check results) or on bottom (after the check results). (default: top) `[$CORTEX_CODE_SUMMARY_POSITION]` |
| `--no-fail-on-crash`        | Returns exit code `0` instead of `2` in case of a failure in the integration with the platform (default: false) `[$CORTEX_CODE_NO_FAIL_ON_CRASH]`                 |
| `--help, -h`                | Displays a help message with available options                                                                                                                    |

## Breakglass: Bypassing the hook

The breakglass feature allows you to intentionally bypass the pre-receive hook security scan. This is useful in urgent situations where a push must go through immediately, but it should be used with caution as it overrides your security policies.

1. Configure your server to accept custom push options:

   ````programlisting
   ```bash
   git config receive.advertisePushOptions true
   ```
   ````
2. Add the `-o breakglass` option to your `git push` command:

   ````programlisting
   ```bash
   git push -o breakglass
   ```
   ````

## Troubleshooting and recommendations

* Refer to the [Cortex CLI](broken://pages/xx6FIRvDVudjs7ygcKZl) for more information on the Cortex CLI.
* Modify the script as required based on the server running the VCS
* The Cortex CLI must be available on the server. This documentation does not describe the CLI installation process
* Update the Cortex CLI periodically
* Instead of adding the API URL and credentials directly in the script, consider creating a `~/.cortexcli/.cortex.yaml` configuration file (owned by the git user and group) with the following contents:

  ```programlisting
  CORTEX_API_BASE_URL: <api base url>
  CORTEX_API_KEY: <api key>
  CORTEX_API_KEY_ID: <api key id>
  ```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-cloud-runtime-security/cortex-cli/cortex-cli-for-code-security/cortex-cli-pre-receive-hooks/pre-receive-hook-usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.