> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/_mcp/server.

# GitHub

> Connect your GitHub account to Pensar Console

# GitHub Integration

Pensar Console integrates with GitHub to scan and secure your repositories. The integration uses a GitHub App to provide secure access to your code without requiring personal access tokens.

## Prerequisites

Before connecting GitHub, ensure you have:

1. **A GitHub account** with access to the repositories you want to scan
2. **Organization owner or admin access** (if installing on an organization)

## Connecting GitHub

### From Workspace Settings

1. Navigate to **Settings** → **Integrations** → **Source control** in your Pensar Console workspace
2. Find the **GitHub** row
3. Click **Connect** (or **Add Account** to connect an additional organization)
4. A popup window will open to GitHub's app installation page
5. Select the organization or user account where you want to install the app
6. Choose to install on **all repositories** or **select specific repositories**
7. Click **Install**
8. You'll be automatically redirected back to Pensar Console

### Direct Installation

You can also install the Pensar GitHub App directly from GitHub:

1. Visit [github.com/apps/pensarapp](https://github.com/apps/pensarapp)
2. Click **Install**
3. Select the organization or user account where you want to install the app
4. Choose your repository access preferences
5. Click **Install**

### From Onboarding

When creating a new workspace, you'll be prompted to connect GitHub during the onboarding process. Simply follow the same steps above.

> **Note**
>
> You can connect multiple GitHub accounts or organizations to the same workspace. This is useful if your code is spread across different GitHub organizations.

## Permissions

The Pensar GitHub App requests the following permissions:

| Permission        | Access Level | Purpose                                                            |
| ----------------- | ------------ | ------------------------------------------------------------------ |
| **Contents**      | Read & Write | Read repository code for scanning, create auto-remediation commits |
| **Pull requests** | Read & Write | Create and manage pull requests for security fixes                 |
| **Checks**        | Read & Write | Report scan status and results on pull requests                    |
| **Actions**       | Read & Write | Integrate with GitHub Actions workflows                            |

> **Note**
>
> When you add repositories, the picker notes that the GitHub App is installed with read-only browsing access — you choose exactly which repositories it can see. The write-level permissions above are only exercised when you opt into auto-remediation (commits and pull requests) for a repository.

## Adding Repositories

After the app is installed, attach repositories directly to your workspace:

1. Go to **Attack Surface** → **Repositories** in Pensar Console
2. Click **Add repository**
3. Your GitHub repositories appear in the picker — select one or more
4. Click **Attach & continue**

Each repository you attach is connected to the workspace and **recon / attack-surface analysis launches automatically** — there is no separate project to create. You can optionally add credentials in the next step, then return to the repository list where a toast links you to the analysis progress.

## Syncing Findings as Issues

Pensar can file each security finding as a GitHub issue in your repository and keep its state in sync. Unlike Linear and Notion, this needs no separate connection — it runs on the GitHub App installation you already have.

### Enabling Sync

1. Navigate to **Settings** → **Integrations** → **Issue tracking**
2. Find the **Issue sync** card and locate the **GitHub Issues** section
3. Turn on **Sync to GitHub** and set a **Severity Filter**

### What Gets Synced

Once enabled, Pensar files each matching finding as a GitHub issue:

* The issue **title** is prefixed with `[Pensar Security]`
* The **body** includes the severity, description, affected location, CWE classification, and a direct link back to the finding in the Pensar Console
* Three **labels** are applied: `security`, `pensar`, and `severity:<level>`

### Where Issues Are Filed

Issues are filed into the repository the finding was found in, when that repository is on GitHub with the Pensar App installed. Findings with no such repository are filed into the workspace's first GitHub-connected repository.

Per-repository settings still apply to **whether** a finding is filed and at **what severity**:

| Setting             | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| **Sync to GitHub**  | Toggle whether findings from this repository are filed as issues |
| **Severity Filter** | The minimum severity required before a finding is filed          |

### Backfilling Existing Findings

Turning on sync only affects findings discovered from that point on. To file findings you already have, use **Sync existing findings** in the **Issue sync** card. Pensar files every open finding that meets the routing and severity rules, skipping any that already has a linked GitHub issue.

### Opening a finding in GitHub

When a GitHub issue already exists for a finding, the finding's actions menu includes **View in GitHub**. Otherwise you can file one from the same menu with **Open as GitHub issue**. That does not require sync to be enabled, only a GitHub repository with the Pensar App installed.

### Two-Way Status Sync

When a finding's status changes in Pensar, the linked issue is updated. This happens wherever the change is made: the console, the REST API, the CLI, MCP, a retest, or a merged pull request. A change that came from GitHub itself is not sent back to it.

| Pensar status  | GitHub issue          |
| -------------- | --------------------- |
| Open           | Open                  |
| In review      | Open                  |
| Closed         | Closed as completed   |
| False positive | Closed as not planned |

GitHub has no in-progress state for issues, so a finding in review stays open.

Changes made in GitHub flow back the same way, through the App's webhook:

| GitHub issue          | Pensar status  |
| --------------------- | -------------- |
| Closed as completed   | Closed         |
| Closed as not planned | False positive |
| Reopened              | Open           |

> **Note**
>
> Inbound reflection can be turned off per provider with **Reflect status changes from GitHub**, in the **GitHub Issues** section. With it off, Pensar remains the source of truth: findings still sync outward to GitHub, but changes made in GitHub are ignored.

## Managing Installations

### Viewing Connected Accounts

1. Navigate to **Settings** → **Integrations** → **Source control**
2. Find the **GitHub** row
3. You'll see all connected GitHub accounts and organizations

### Adding More Accounts

Click **Add Account** in the GitHub row to connect additional GitHub organizations or user accounts.

### Modifying Repository Access

To change which repositories Pensar can access:

1. Go to your GitHub organization or account settings
2. Navigate to **Installed GitHub Apps**
3. Find **Pensar** and click **Configure**
4. Update the repository access settings
5. The changes will be reflected in Pensar Console automatically

### Removing an Installation

To disconnect a GitHub account:

1. Go to your GitHub organization or account settings
2. Navigate to **Installed GitHub Apps**
3. Find **Pensar** and click **Configure**
4. Scroll down and click **Uninstall**

> **Warning**
>
> Removing a GitHub installation will prevent Pensar from scanning repositories in that account. Any repositories attached to your workspace from that account will no longer be able to perform scans.

## Troubleshooting

### Installation Pending Approval

If you see "Installation pending approval", it means you requested to install the app on an organization where you're not an admin. An organization owner will need to approve the installation.

### Repositories Not Appearing

If your repositories don't appear in the **Add repository** picker:

1. Verify the GitHub App is installed on the correct organization
2. Check that the app has access to the specific repository
3. Ensure you have at least read access to the repository on GitHub

### Permission Errors

If you see permission errors when scanning:

1. Verify the GitHub App has the required permissions listed above
2. Ensure the app is installed on the repository you're trying to scan
3. Check that the installation hasn't been suspended

## Need Help?

If you encounter issues setting up your GitHub integration, please contact our support team at [team@pensar.dev](mailto:team@pensar.dev).