# Setting Up the Panther GitHub App (Beta)
{% hint style="warning" %}
The Panther GitHub App is in open beta starting with Panther version 1.125. Please share any bug reports and feature requests with your Panther support team.
{% endhint %}
## Overview
Installing the Panther GitHub App on your detection content repository allows Panther to open pull requests in your repository on your behalf. Once the app is installed, edits to supported detection types in the Panther Console produce pull requests in your repository instead of writing directly to Panther—see [Creating a GitHub pull request from the Panther Console](/panther-developer-workflows/overview.md#creating-a-github-pull-request-from-the-panther-console) for the list of supported types.
The setup process involves **two roles**, which may be filled by two different people or by the same person:
* A **Panther user** with the `Edit Settings & SAML Preferences` permission, who configures the git repository in the Panther Console and generates a registration link.
* A **GitHub organization owner**, who opens the registration link and completes the app registration and installation on GitHub. This person does **not** need a Panther account.
The Panther user generates the link and shares it—along with the name of the target repository—with the GitHub organization owner (by email, Slack, or any other channel). The link is valid for **24 hours** and can only be used once. Generating a new link invalidates the previous one.
## Prerequisites
* All of your Panther detection content is in a **single** GitHub repository. The Panther GitHub App does not support integrating with multiple repositories at this time.
* The person who opens the registration link must be an **owner** of the GitHub organization that contains your detection repository. GitHub does not allow non-owners to register an app on behalf of the organization.
## Step 1: Configure the repository and generate a registration link (Panther user)
{% hint style="warning" %}
Saving the repository configuration immediately changes how the Panther Console handles edits to supported detection types: instead of saving directly to Panther, the Console opens a pull request against your repository ([Create PR](/panther-developer-workflows/overview.md#creating-a-github-pull-request-from-the-panther-console) mode). Until the Panther GitHub App is installed and connected to that repository, Create PR will fail, so Console edits to those detection types will be blocked. Save the configuration only when your team is ready for this change in behavior.
{% endhint %}
1. In the Panther Console, click the gear icon in the upper-right corner and select **General**.
2. Click the **Developer Workflow** tab.
3. In the **Git Sync** section, fill in the fields:
* **GitHub Organization**: the name of the GitHub organization that owns your detection repository.
* **Repository Name**: the name of the repository that contains your Panther detection content.
* **Branch Name**: the branch that Panther should submit [pull requests](/panther-developer-workflows/overview.md#creating-a-github-pull-request-from-the-panther-console) against for Console-originated changes—typically `main` or `master`.
4. Click **Save Repository**. The **GitHub App Registration** section appears below, and **Edit Connection** and **Disconnect** buttons appear next to the configuration fields. You can use these buttons at any time—see [Editing or removing the integration](#editing-or-removing-the-integration) for the effect of each.
Before clicking Generate Registration Link in the next step, confirm that a GitHub organization owner is available to complete the registration on GitHub within 24 hours—that's how long the generated link stays valid.
5. Click **Generate Registration Link**. Panther displays the full URL in the **Registration Link** field.
6. Click **Copy** and share two pieces of information with the GitHub organization owner:
* The registration link.
* The name of the target repository (from the **Repository Name** field above), so they can select it correctly when installing the app.
{% hint style="info" %}
A registration link is invalidated whenever **any** Panther user with the `Edit Settings & SAML Preferences` permission clicks **Generate Registration Link**—including a different user who opens the Panther Console and generates a link independently. If a link you shared stops working, check whether anyone else on your team may have generated a new one, and re-share the current link along with the repository name.
{% endhint %}
## Step 2: Open the registration link (GitHub organization owner)
The GitHub organization owner opens the link in a browser. No Panther account is required.
The page shows the GitHub organization the app will be registered for and the link's expiry time. The GitHub organization owner clicks **Continue to GitHub**.
If an error appears instead of the registration details, see [An error appears when first opening the link](#an-error-appears-when-first-opening-the-link).
## Step 3: Create the GitHub App on GitHub
GitHub displays a form with a pre-filled app name (e.g., `{your-org}-panther-gh-app`). The GitHub organization owner can change the name if they like, but it must be unique across all of GitHub.
The GitHub organization owner clicks **Create GitHub App**. If the registration succeeds, GitHub takes them to the app installation page. Otherwise, the browser lands on an error page—either GitHub's own error, or Panther's registration page with an error message:
* If GitHub rejects the app name, see [The app name is already taken on GitHub](#the-app-name-is-already-taken-on-github).
* If the browser is redirected back to the Panther registration page with an error, see [An error appears after clicking Create GitHub App or Install](#an-error-appears-after-clicking-create-github-app-or-install).
## Step 4: Install the app on the target repository
On GitHub's installation page, the GitHub organization owner selects **Only select repositories**, chooses the target repository (the one shared by the Panther user in Step 1), and clicks **Install**.
{% hint style="warning" %}
Install the app on only the target repository. Installing on any other combination of repositories will result in a warning or error in the Panther Console—see [The app was installed, but Panther can't access the target repository](#the-app-was-installed-but-panther-cant-access-the-target-repository) and [The app was installed on multiple repositories, including the target](#the-app-was-installed-on-multiple-repositories-including-the-target).
{% endhint %}
If the installation succeeds, GitHub redirects the browser back to the Panther Console—if the GitHub organization owner is not logged in to Panther (the typical case), they land on the Panther login page. They can close the tab; their involvement ends here.
If an error occurs, the browser is redirected back to the Panther registration page with an error message—see [An error appears after clicking Create GitHub App or Install](#an-error-appears-after-clicking-create-github-app-or-install).
## Step 5: Review the result in the Panther Console (Panther user)
Panther automatically runs a connection test against your configured repository and delivers a notification in the Panther Console. Panther users with the `Edit Settings & SAML Preferences` permission receive this notification; it cannot be unsubscribed from.
If the installation succeeded and the app has access to the target repository, the Panther user receives a success notification:
You can also verify the connection on **Settings** > **General** > **Developer Workflow**. The **Sync Status** section displays the outcome of the most recent test, and the **Test Configuration** section shows whether the repository is accessible and the configured branch exists. You can re-run the test at any time by clicking **Test Connection** in the **Test Configuration** section:
Once you see a success notification, your git integration is fully configured. You can now [create pull requests from the Panther Console](/panther-developer-workflows/overview.md#creating-a-github-pull-request-from-the-panther-console) when editing or creating detections.
If instead the notification is a warning or error, see:
* **Warning**: [The app was installed on multiple repositories, including the target](#the-app-was-installed-on-multiple-repositories-including-the-target).
* **Error**: [The app was installed, but Panther can't access the target repository](#the-app-was-installed-but-panther-cant-access-the-target-repository).
## Editing or removing the integration
The Panther user can edit the repository configuration or remove the integration entirely from the **Git Sync** section of **Settings** > **General** > **Developer Workflow**. Both options are available at any point after the configuration is first saved—including while a registration flow is in progress.
* **Edit Connection** opens the **GitHub Organization**, **Repository Name**, and **Branch Name** fields for editing. Editing the configuration does not affect a registration flow that is currently in progress.
* **Disconnect** is the clean uninstall path. Clicking **Disconnect** removes the repository configuration entirely and uninstalls the Panther GitHub App from your repository. This also invalidates any in-progress registration link, and returns the Panther Console to its default detection-save behavior (no longer routing edits through Create PR). Existing pull requests in GitHub are unaffected and remain open.
To set up the integration again after disconnecting, restart from [Step 1](#step-1-configure-the-repository-and-generate-a-registration-link-panther-user).
## Troubleshooting
### An error appears when first opening the link
If the GitHub organization owner opens the registration link and immediately sees an error instead of the registration details:
The most likely causes are:
* **The link was copied incorrectly.** If the link was shared over a channel that truncated or mangled the URL (for example, a chat client that split it across lines), copy the link again from the Panther Console and re-share it.
* **The link has expired.** Registration links are valid for 24 hours from the time they are generated.
To recover, the Panther user returns to [Step 1](#step-1-configure-the-repository-and-generate-a-registration-link-panther-user) and generates a fresh registration link, then shares it—along with the repository name—with the GitHub organization owner. The GitHub organization owner then restarts the flow from [Step 2](#step-2-open-the-registration-link-github-organization-owner).
### An error appears after clicking Create GitHub App or Install
If the GitHub organization owner successfully loads the registration page, clicks through to GitHub, and completes either **Create GitHub App** or **Install**, but is then redirected back to the Panther registration page with an error message:
The most likely causes are:
* **The link expired during the flow.** The GitHub steps took longer than 24 hours to complete, so the server-side expiry check failed.
* **The link was superseded.** A Panther user generated a new registration link while the flow was in progress. Generating a new link invalidates any earlier link, even one that is currently being used.
* **A validation error occurred on Panther's side** when exchanging credentials with GitHub.
A GitHub App may already exist in the GitHub organization at this point, depending on how far the flow progressed before the error.
To recover:
1. The GitHub organization owner opens the GitHub organization in a browser, clicks **Settings**, then in the left sidebar expands **Developer settings** and clicks **GitHub Apps**:
The page lists the GitHub Apps registered to the organization. If a partially registered Panther app is present, click **Edit** on its row:
In the app's settings, open the **Advanced** tab and scroll to the **Danger zone** section, then click **Delete GitHub App**:
Read the confirmation dialog carefully, then type the GitHub App name into the confirmation field:
Once the name matches, the **I understand the consequences, delete this GitHub App** button becomes active. Click it to delete the app:
2. The Panther user returns to [Step 1](#step-1-configure-the-repository-and-generate-a-registration-link-panther-user) and generates a fresh registration link, then shares it—along with the repository name—with the GitHub organization owner.
3. The GitHub organization owner restarts the flow from [Step 2](#step-2-open-the-registration-link-github-organization-owner).
### The GitHub organization owner is not actually an organization owner
GitHub requires that the person completing the app registration is an **owner** of the target organization. If the person opening the link is a member but not an owner, GitHub displays a banner at the top of the **Create GitHub App** page in Step 3 explaining that they don't have permission:
To recover, have a GitHub organization owner open the registration link. If the original link is still within its 24-hour window, it can be reused—no need to generate a new one.
### The app name is already taken on GitHub
GitHub App names must be unique across all of GitHub. If the pre-filled name is already taken, clicking **Create GitHub App** in Step 3 surfaces a "Name is already taken" error tooltip on the **GitHub App name** field:
To recover, the GitHub organization owner edits the **GitHub App name** field to a unique value and clicks **Create GitHub App** again. The rest of the flow is unaffected.
### The app was installed, but Panther can't access the target repository
This happens in two scenarios:
* The app was installed on a **single repository** that is not the target repository. The Panther user receives this error notification:
* The app was installed on **multiple repositories**, none of which is the target repository. The Panther user receives this error notification:
In both cases, the integration will not work until the installation is updated. To recover, follow the steps in [Updating the app's repository access on GitHub](#updating-the-apps-repository-access-on-github) to set the target repository as the only repository the app can access.
The Panther user can confirm the fix worked by returning to **Settings** > **General** > **Developer Workflow** and clicking **Test Connection** under the **Test Configuration** section. After a successful test, the section displays green checkmarks next to **Repository accessible** and **Branch \[name] exists**:
### The app was installed on multiple repositories, including the target
If the app is installed on multiple repositories *and* the target repository is among them, the integration will work—but the app has more access than Panther needs. The Panther user receives a warning notification recommending that access be restricted to only the detection repository:
To follow the principle of least privilege, the GitHub organization owner can restrict the installation by following the steps in [Updating the app's repository access on GitHub](#updating-the-apps-repository-access-on-github). Because the connection test already passes in this scenario, Panther cannot detect the change—the Panther user should confirm directly with the GitHub organization owner that the unrelated repositories have been removed.
### Updating the app's repository access on GitHub
The GitHub organization owner can update which repositories the Panther GitHub App can access at any time, without going through the registration flow again. Use these steps to add the target repository to the installation, remove repositories the app shouldn't have access to, or both.
1. Open the GitHub organization in a browser, click **Settings**, then in the left sidebar under **Third-party Access** click **GitHub Apps**:
2. On the **Installed GitHub Apps** page, find the Panther app and click **Configure**:
3. Scroll to the **Repository access** section. With **Only select repositories** chosen, click the repository selector to add or remove repositories:
4. Adjust the selection so that the target repository is listed and any unrelated repositories are removed. Click **Save**:
---
# Agent Instructions: 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:
```
GET https://docs.panther.com/panther-developer-workflows/detections-repo/github-app.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.