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

# GitHub Identity Setup Guide

> Walk through the end-to-end process of configuring GitHub App authentication, repository integration, and catalog ingestion in Portal.

## Overview

The Admin interface allows you to configure authentication providers, integrations, and admin settings for your Portal instance. This comprehensive guide walks you through the complete end-to-end GitHub setup process.

<Note>
  **What You'll Accomplish**

  By the end of this guide, you'll have a fully configured Portal instance with GitHub authentication, repository integration, and catalog ingestion running.
</Note>

## Prerequisites

Before starting, ensure you have:

* ✅ Portal instance with root auth provider enabled
* ✅ GitHub App credentials (App ID, Client ID, Client Secret, Private Key)
* ✅ Access to a GitHub organization for catalog ingestion
* ✅ Admin permissions in your GitHub organization

### GitHub App Permissions Required

#### Repository permissions:

<Note>
  **Repository Permissions Required for GitHub App**

  | Permission                     | Access Level | Why Required                                                              |
  | ------------------------------ | ------------ | ------------------------------------------------------------------------- |
  | Administration                 | Read / Write | Enables Portal to manage repository settings, webhooks, and collaborators |
  | Actions                        | Read / Write | Allows Portal to view and trigger GitHub Actions workflows                |
  | Code scanning alerts           | Read         | Provides access to security vulnerabilities detected in code              |
  | Commit statuses                | Read         | Enables Portal to display build and test statuses on commits              |
  | Contents                       | Read / Write | Allows Portal to read repository files and create/update scaffolded code  |
  | Deployments                    | Read         | Allows Portal to view GitHub Deployments                                  |
  | Dependabot alerts              | Read         | Provides access to dependency vulnerability alerts                        |
  | Issues                         | Read / Write | Enables Portal to create, view, and manage repository issues              |
  | Metadata                       | Read         | Required for basic repository information access                          |
  | Pull requests                  | Read / Write | Allows Portal to create and manage pull requests for code changes         |
  | Repository security advisories | Read         | Provides access to security advisory information                          |
  | Secret scanning alerts         | Read         | Allows Portal to access detected leaked secrets in repositories           |
</Note>

#### Organization permissions:

<Note>
  **Organization Permissions Required for GitHub App**

  | Permission | Access Level | Why Required                                                                                   |
  | ---------- | ------------ | ---------------------------------------------------------------------------------------------- |
  | Members    | Read         | Allows Portal to access organization member information for user management and authentication |
</Note>

### How to find your Client ID and Secret

If you have previously registered an OAuth app, you can find your Client ID by visiting your app in the
[developer settings](https://github.com/settings/developers). If you can't find your Client Secret you can generate a new one and copy it over.

If you haven't previously registered an OAuth app in GitHub, you will need to create it under your GitHub organization
under [developer settings](https://github.com/settings/developers). Once your app is registered, a Client ID and Secret will be generated.
Copy and store your secret somewhere safely as you won't be able to see it again later.

***

## Step 1: Initial Setup and Organization Configuration

### Configure Your Organization Name

1. **Sign in** to your Portal instance as the root user
2. **Navigate** to **Admin → App Settings → General**
3. **Update your organization name:**
   * Enter your desired organization name (e.g., "Demo Company")
   * Click **"Save Changes"**

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-auth/github_home_page_image_one_blur.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=e8cb2d58cfeb9f974e59dc6bdc44bbdc"
    alt="Organization name configuration in Admin
settings"
    width="2008"
    height="831"
    data-path="portal/assets/github-auth/github_home_page_image_one_blur.png"
  />
</Frame>

<Tip>
  The organization name will appear in the catalog title and throughout Portal,
  creating a branded experience for your users.
</Tip>

***

## Step 2: Configure Authentication Provider

### Set Up GitHub Authentication

1. **Navigate** to **Admin → App Settings → Auth**

2. You'll see all available auth providers (none configured initially)

3. **Select GitHub** to configure:
   * **Client ID**: Enter your GitHub App Client ID
   * **Client Secret**: Enter your GitHub App Client Secret
   * **Enterprise Instance URL**: (Optional) For GitHub Enterprise Server
   * **Resolver**: Select the appropriate user resolution method
   * Click **"Save"**

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-auth/github_auth_page_image_two.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=de017f3498c708437de774c1fcf99fd6"
    alt="GitHub authentication provider
configuration"
    width="2025"
    height="831"
    data-path="portal/assets/github-auth/github_auth_page_image_two.png"
  />
</Frame>

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-auth/github_integration_image_three_blur.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=e3caddbc44cb933d38e2a6743fdca612"
    alt="GitHub App integration
configuration"
    width="1930"
    height="842"
    data-path="portal/assets/github-auth/github_integration_image_three_blur.png"
  />
</Frame>

<Warning>
  **Important**

  Once you have only one auth provider configured, you cannot stop it. The system will provide context explaining why this restriction exists.
</Warning>

***

## Step 3: Set Up GitHub Integration

### Configure GitHub App Integration

1. **Navigate** to **Admin → App Settings → Integrations**
2. **Configure the GitHub App:**
   * **App ID**: Your GitHub App ID
   * **Client ID**: Your GitHub App Client ID
   * **Client Secret**: Your GitHub App Client Secret
   * **Private Key**: Paste your GitHub App private key
   * Click **"Add Item"**
   * Click **"Save"**

<Warning>
  **Validation Tip**

  Ensure there are no blank spaces before the integration URLs, as this can cause validation failures.
</Warning>

**Multiple Integrations**: You can configure multiple GitHub integrations if your organization uses multiple GitHub instances or apps.

***

## Step 4: Configure Catalog Settings

Since adding users requires them to exist in the catalog, you need to set up catalog ingestion first.

### Access Catalog Configuration

1. **Navigate** to **Admin → Catalog Settings**
2. Set up catalog ingestion for both components and organizational data
3. Configure GitHub as your catalog source

### Component Ingestion Setup

**Ingest Repository Components:**

1. Click **"Ingest"** for components
2. **Configure the repository:**
   * **Repository**: `backstage-portal-demo` (or your target repo)
   * **Path**: Use default `catalog-info.yaml` path
   * **Schedule**: Set up ingestion frequency as needed
   * **GitHub URL**: Add your GitHub organization URL
3. Click **"Save"**

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-auth/github_ingestion_image_four.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=12fae101b77838ed6bf856ebda750f48"
    alt="Component ingestion
configuration"
    width="1916"
    height="849"
    data-path="portal/assets/github-auth/github_ingestion_image_four.png"
  />
</Frame>

### User and Group Ingestion Setup

**Sync Organizational Data:**

1. **Configure user/group sync:**
   * **Repository**: `backstage-portal-demo` (or your target repo)
   * **Sync Interval**: Set appropriate frequency
   * **Organization**: Your GitHub organization name
2. Click **"Save"**

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-auth/github_ingestion_image_four_five_blur.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=3a290570bcdb6e0b381956d785fe5ad1"
    alt="User and group ingestion
setup"
    width="1905"
    height="838"
    data-path="portal/assets/github-auth/github_ingestion_image_four_five_blur.png"
  />
</Frame>

<Note>
  **Processing Time**

  The system will begin ingesting both components and users/groups into the catalog. This process may take a few seconds to several minutes depending on your organization size.
</Note>

***

## Step 5: Add Portal Administrators

### Grant Admin Access

Once users are ingested into the catalog:

1. **Navigate** to **Admin → App Settings → Users**
2. **Add additional admins** to your Portal instance:
   * **Groups**: Add admin groups (e.g., `group:default/admins`)
   * **Individual Users**: Add specific users (e.g., `user:default/jane.doe`)
3. Click **"Save Changes"**

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-auth/github_admin_assignment_image_five_blur.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=015703e057fe36ef9ced4c54813ab490"
    alt="Admin user assignment
configuration"
    width="1940"
    height="841"
    data-path="portal/assets/github-auth/github_admin_assignment_image_five_blur.png"
  />
</Frame>

<Tip>
  **Entity References**

  Use the format `user:default/username` for individual users and `group:default/groupname` for groups, where the names match your GitHub organization structure.
</Tip>

***

## Step 6: Verify Setup

### Test Your Configuration

1. **Add yourself as an admin** (if not already done)
2. **Sign out** from the root account
3. **Sign in** with your GitHub user credentials
4. **Verify** you have access to the Admin interface

<Check>
  **Setup Complete!**

  You now have a fully configured Portal instance with GitHub authentication, integration, and catalog ingestion. Your team can start using Portal with their GitHub credentials.
</Check>

***

## Troubleshooting

### Common Issues and Solutions

| Issue                    | Solution                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------ |
| **Validation failures**  | Check for blank spaces before URLs in integration fields                             |
| **Ingestion issues**     | Ensure GitHub App has proper permissions to access target repositories               |
| **Auth provider issues** | Remember you cannot stop the last remaining auth provider                            |
| **User not found**       | Verify the user exists in your GitHub organization and catalog ingestion is complete |
| **Permission denied**    | Check that the user is added to the authorized users list in Admin                   |

### Need More Help?

* **Authentication Issues**: Review the GitHub Auth Setup documentation
* **Integration Problems**: Check the GitHub Integration Troubleshooting guide
* **General Support**: Visit the Troubleshooting Section

***

## Next Steps

With GitHub setup complete, consider these additional configurations:

* **Enable additional plugins** in Admin → Plugin Settings
* **Configure TechDocs** for documentation hosting
* **Set up Scaffolder templates** for standardized project creation
* **Customize the Portal theme** and branding options