> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rad.security/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub (App)

> Connect GitHub to RAD Security for repository scanning, dependency analysis, and organization visibility.

# GitHub (App) Integration Setup

This guide walks you through connecting GitHub to RAD Security using the RAD Security App, enabling repository discovery, dependency graph analysis, code scanning, and organization visibility.

## Prerequisites

RAD Security currently only supports the `user-to-server` mechanism for authentication for the GitHub App integration. This means that in addition to the app being installed in the organisation, it also needs to be authorized to act on a user's behalf. It is strongly recommended that a Service Account in your GitHub organization is created for this purpose.

Before you begin, ensure you have:

<Check>Admin access to your GitHub organization (to create Service Account and install the app)</Check>
<Check>Access to RAD Security workspace with integration permissions</Check>
<Check>Understanding of which repositories need to be scanned (public, private, or both)</Check>

***

## Create Service Account

The RAD Security GitHub App uses `user-to-server` authentication to operate with permissions that are the **intersection** of three factors:

1. **App's granted permissions** - What the GitHub App has been configured to access
2. **Installation permissions** - Which repositories the app was installed with access to
3. **Service account permissions** - What the authorizing user account can access

This intersection model gives you fine-grained control, allowing you to further restrict the permissions RAD Security has by providing the Service Account with a subset of permissions.

<Steps>
  <Step title="Create a GitHub account for RAD Security">
    Create a new GitHub user account (or use an existing service account) that will be dedicated to RAD Security integration. We recommend naming it something like `rad-security-bot`.
  </Step>

  <Step title="Add account to your organization">
    Invite the service account to your GitHub organization with the **Member** role (not Owner). This limits the account's base permissions.
  </Step>

  <Step title="Grant repository access">
    Add the service account to teams or grant direct repository access for the repositories you want RAD Security to scan. The service account needs **read** access to:

    * Repository contents
    * Repository metadata
    * Dependency graphs (automatically granted with repo read access)
  </Step>

  <Step title="Grant organization read permissions">
    To enable organization visibility features, ensure the service account can read organization membership. This is typically granted by default to organization members, but verify in your organization settings under **Member privileges**.
  </Step>
</Steps>

<Note>
  **Important**: The service account does not need any write permissions. RAD Security operates in read-only mode for security analysis.
</Note>

***

## Install GitHub App

Before authorizing the app in RAD Security, you must install the RAD Security GitHub App in your organization.

<Steps>
  <Step title="Navigate to the RAD Security App">
    Visit the [RAD Security GitHub App page](https://github.com/apps/rad-security)
  </Step>

  <Step title="Click Install">
    Click the green **Install** button.
  </Step>

  <Step title="Select organization">
    Choose the GitHub organization where you want to install the app. You must have admin access to the organization to complete this step.
  </Step>

  <Step title="Choose repository access">
    Select which repositories the app can access:

    * **All repositories** - Recommended for comprehensive security coverage
    * **Only select repositories** - Choose specific repositories if you want to limit scope

    <Warning>
      The app can only access repositories you grant here. This selection can be changed later in your organization's GitHub App settings.
    </Warning>
  </Step>

  <Step title="Complete installation">
    Review the permissions requested by the app and click **Install**. The app requests:

    * **Contents** (read-only) - Read repository and package contents
    * **Metadata** (read-only) - Read repository metadata
    * **Organization members** (read-only) - Read organization membership information
  </Step>
</Steps>

<Note>
  The installation grants the app **access to repositories**, but does not yet allow RAD Security to use it. You must complete the authorization flow in the next step.
</Note>

***

## Configure in RAD Security

After installing the app in your GitHub organization, configure the integration in RAD Security:

<Steps>
  <Step title="Navigate to Integrations">
    Go to your RAD Security workspace and navigate to **Data Sources** → **Integrations**.
  </Step>

  <Step title="Select GitHub (App)">
    Find and click on **GitHub (App)** from the list of available integrations.
  </Step>

  <Step title="Enter Integration Details">
    You'll be taken to a screen where you need to enter:

    * **Integration Name**: A descriptive name for this integration (e.g., `GitHub - Acme Org`)

    Click **Connect with OAuth** to begin the authorization flow.
  </Step>

  <Step title="Authorize with Service Account">
    You'll be redirected to GitHub's authorization page. You can either:

    * Select the service account from the account picker if already signed in
    * Sign in as the service account if not already signed in

    Review the authorization request and click **Authorize** to complete.
  </Step>

  <Step title="Return to RAD Security">
    After authorization, you'll be automatically redirected back to the integration summary page for your GitHub App integration.
  </Step>
</Steps>

<Info>
  **Token Management**: The tokens RAD Security uses expire and are automatically refreshed. You'll only need to re-authorize after 6 months of inactivity or if you revoke the authorization in GitHub.
</Info>

***

## Verify Integration

After completing the authorization flow, verify your integration is working:

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Data Sources** → **Integrations** and locate your GitHub App integration.
  </Step>

  <Step title="Check Integration Status">
    Verify that:

    * The status shows **Connected**
    * The **Login** field displays your service account username (e.g., `rad-security-bot`)

    This confirms the authorization was completed with the correct account.
  </Step>
</Steps>

<Check>
  Your GitHub App integration is now configured! RAD Security will now be able to scan your GitHub repositories and packages.
</Check>

***

## What Data is Used

<AccordionGroup>
  <Accordion title="Repository Information" icon="folder">
    * Repository names and metadata
    * Visibility settings (public/private)
    * Default branch information
    * Repository topics and descriptions
  </Accordion>

  <Accordion title="Dependency Data" icon="sitemap">
    * Software Bill of Materials (SBOM) via Dependency Graph API
    * Direct and transitive dependencies
    * Dependency versions and sources
    * Manifest file contents (package.json, requirements.txt, etc.)
  </Accordion>

  <Accordion title="Organization Data" icon="building">
    * Organization membership
    * Team structures (if accessible)
    * Member roles and permissions
  </Accordion>

  <Accordion title="Package Registry" icon="box">
    * Published packages
    * Package versions
    * Package metadata
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="Dependency Vulnerability Detection" icon="bug">
    Identify vulnerable dependencies across all repositories using SBOM data and known vulnerability databases.
  </Card>

  <Card title="Software Supply Chain Visibility" icon="link">
    Map your complete software supply chain by tracking all direct and transitive dependencies.
  </Card>

  <Card title="Code Security Analysis" icon="magnifying-glass">
    Search code across repositories for security anti-patterns, secrets, or vulnerable code constructs.
  </Card>

  <Card title="Organization Security Posture" icon="shield-halved">
    Monitor organization membership and repository access to identify potential security risks.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Private Repositories Not Appearing" icon="folder-xmark">
    * Confirm the app is installed in the organization with access to the desired repositories
    * Confirm the service account has the correct permissions to access the desired repositories
    * Check if the repositories are in an organization that requires SSO authentication
  </Accordion>

  <Accordion title="Organization Data Missing" icon="building-circle-xmark">
    * Verify the Service Account has the permission to read organization data
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Engineering Integrations Overview" icon="code-branch" href="/rad-security/integrations/engineering/overview">
    Learn about other engineering integrations
  </Card>

  <Card title="Evidence Room" icon="vault" href="/rad-security/platform/evidence-room">
    View and analyze collected security data
  </Card>
</CardGroup>