# GitHub (App)

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



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:

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

---

## 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>

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

---

## 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

    <Callout kind="alert">
      The app can only access repositories you grant here. This selection can be changed later in your organization's GitHub App settings.
    </Callout>
  </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>

<Callout kind="info">
  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.
</Callout>

---

## 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>

<Callout kind="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.
</Callout>

---

## 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>

<Callout kind="success">
  Your GitHub App integration is now configured! RAD Security will now be able to scan your GitHub repositories and packages.
</Callout>

---

## What Data is Used

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

  <Expandable 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.)
  </Expandable>

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

  <Expandable title="Package Registry" icon="box">
    - Published packages
    - Package versions
    - Package metadata
  </Expandable>
</ExpandableGroup>

---

## Use Cases

<Columns cols={2}>
  <div>
  **Dependency Vulnerability Detection**
    Identify vulnerable dependencies across all repositories using SBOM data and known vulnerability databases.
  </div>
  <div>
  **Software Supply Chain Visibility**
    Map your complete software supply chain by tracking all direct and transitive dependencies.
  </div>
  <div>
  **Code Security Analysis**
    Search code across repositories for security anti-patterns, secrets, or vulnerable code constructs.
  </div>
  <div>
  **Organization Security Posture**
    Monitor organization membership and repository access to identify potential security risks.
  </div>
</Columns>

---

## Troubleshooting

<ExpandableGroup>
  <Expandable 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
  </Expandable>

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

---

## Next Steps

<Columns 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>
</Columns>