> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/app-pipeline-integration/github-app.md).

# GitHub App

OX Security supports pipeline scanning using the GitHub App, which uses GitHub webhooks to trigger scans.

This approach does not require modifying CI/CD configurations or adding the OX CLI to pipeline jobs. Instead, OX listens for GitHub events and initiates scans automatically.

OX detects pull requests and push events directly from GitHub. Based on the event, OX identifies the modified files and performs a scan.

The scan runs outside your pipeline and reports results in the OX UI. No CLI or container is needed inside your GitHub workflow.

#### GitHub Merge Queue support

> **Note:**
>
> * This capability is currently in Early Access (EA) and is not generally available. To request access, please contact OX technical support.

GitHub Merge Queue is a GitHub capability that validates pull requests in a temporary merge queue before they are merged into a protected branch. Instead of merging pull requests individually, GitHub creates a temporary combined branch and runs the required checks against that state.

OX can scan Merge Queue events when using GitHub App pipeline integration.

Merge Queue scans use the same pipeline configuration that is defined for pull request events. No additional configuration is required in OX. Any policies, checks, and blocking behavior configured for pull requests are automatically applied to Merge Queue runs. If a blocking OX policy fails, GitHub prevents the queued changes from being merged until the issues are resolved.

After the capability is enabled, OX automatically analyzes Merge Queue runs and displays the results on the [Pipeline Summary](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results/pipeline-summary.md) page.

## Prerequisites

* The GitHub App must be installed in your GitHub organization.
* [You must grant the app access to the repositories you want to scan.](/get-started/onboarding-to-ox/source-control/github.md)

## Required Configuration

OX initiates scans using webhook data from GitHub. You do not need to add variables or modify settings. You just need to [make sure that webhooks are enabled.](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/webhooks-pipeline-integration.md)

## Block pull request merges based on OX scan results

You can configure GitHub branch protection rules to prevent pull requests from being merged when OX detects issues that match your blocking policies.

When OX scans a pull request, it reports the scan result to GitHub as the **ox-security/scan** status check. If the scan finds blocking issues, the status check fails, and GitHub can prevent the merge.

**To require OX scans before merging:**

1. In GitHub, open the repository and select **Settings** > **Branches**.

<figure><img src="/files/WSZkLy46cwyC03wj3Viw" alt="" width="563"><figcaption></figcaption></figure>

2. Create a new branch protection rule or edit an existing rule for the target branch (for example, `main`).
3. Under **Protect matching branches**, select **Require status checks to pass before merging**.
4. (Optional) Select **Require branches to be up to date before merging**.
5. In the required status checks list, add **ox-security/scan**.
6. Save the rule.

After the rule is configured, pull requests cannot be merged until the **ox-security/scan** check completes successfully. If OX finds issues that match your blocking policies, the check fails and GitHub blocks the merge until the issues are resolved.

> **Note**
>
> The `ox-security/scan` status check appears after OX has processed pull requests for the repository.


---

# 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://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/app-pipeline-integration/github-app.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.