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

# Migrating to a GitHub App Integration

> Migrate Portal from a Personal Access Token to a GitHub App for organization-level permissions, automatic commit signing, and shared credential management.

This guide will help you migrate your Portal instance from a Personal Access Token (PAT) to a GitHub App integration.

## Why migrate to a GitHub App Integration?

Migrating from a Personal Access Token to a GitHub App provides several key advantages:

### Security & Management Benefits

* **Organization-level installation**: GitHub Apps can be installed at the organization level instead of being tied to a specific user account
* **Granular permissions**: More precise control over repository and organization permissions
* **Automatic commit signing**: All commits made on behalf of Portal will be automatically signed
* **Reduced credential risk**: Eliminates the risk of orphaned or compromised personal credentials
* **Shared ownership**: Easier management and shared ownership within your organization

### Comparison: PAT vs GitHub App

| Feature                   | Personal Access Token        | GitHub App                           |
| ------------------------- | ---------------------------- | ------------------------------------ |
| **Scope**                 | User-level access            | Organization-level installation      |
| **Permissions**           | Broad, user-based scopes     | Granular, app-specific permissions   |
| **Ownership**             | Tied to individual user      | Owned by organization                |
| **Commit Signing**        | Manual setup required        | Automatic                            |
| **Credential Management** | User manages token lifecycle | Organization manages app credentials |

## Prerequisites

Before you start the migration, ensure you have:

* Portal setup with current PAT-based GitHub integration
* Access to **App Settings**
* Administrative access to your GitHub organization
* Permission to create and configure GitHub Apps in your organization

## Migration Steps

### 1. Create and Configure GitHub App

Follow the comprehensive GitHub App setup instructions in our [Getting Started Guide](../auth/github), which includes:

* Complete permission requirements and explanations
* Step-by-step GitHub App creation process
* Required repository and organization permissions with detailed reasoning

<Tip>
  **Migration-Specific Notes**

  When creating your GitHub App for migration:

  * **Create under your GitHub organization** (not personal account) for easier management
  * **Install on the same repositories** currently accessed via your PAT
  * **Save all credentials securely** before proceeding to configuration updates
</Tip>

### 2. Gather GitHub App Credentials

After creating your GitHub App, collect the following information:

* **App ID**: Found in your GitHub App settings
* **Private Key**: Generated and downloaded during app creation
* **Client ID**: Available in your GitHub App settings
* **Client Secret**: Generated in your GitHub App settings
* **Webhook Secret**: Set during GitHub App creation

<Warning>
  **Security Note**

  Store these credentials securely. The private key and client secret cannot be retrieved again once you navigate away from the GitHub interface.
</Warning>

### 3. Update Portal Configuration

Now migrate your Portal configuration from PAT to GitHub App:

1. **Access App Settings**

   * Navigate to `/admin/app-settings/integrations/github`
   * Or go to **App Settings** → **Integrations**

2. **Remove PAT Configuration**

   * Expand **integrations** → **github** → **Github-1** sections
   * Locate the `token` field (your current PAT)
   * Click the `×` button to remove the token field

3. **Add GitHub App Configuration**

   * In the same **Github-1** section, expand the **apps** section
   * Click **+ Add Item** to create a new **apps-1** section
   * Expand the new **apps-1** section and add these fields:
     * `appId`: Your GitHub App ID
     * `privateKey`: The private key content (including headers/footers)
     * `webhookSecret`: Your webhook secret
     * `clientId`: Your GitHub App Client ID
     * `clientSecret`: Your GitHub App Client Secret

4. **Save Configuration**
   * Scroll to the bottom and click **Save changes**
   * Portal will restart with the new GitHub App integration

### 4. Verify Migration Success

After saving your configuration:

1. **Check Portal Startup**

   * Monitor Portal logs for successful GitHub App authentication
   * Ensure no authentication errors appear

2. **Test GitHub Integration**

   * Navigate to your Software Catalog
   * Verify that GitHub repositories are still discoverable
   * Test creating a new component or service (if applicable)
   * Confirm that GitHub-based features work as expected

3. **Validate Permissions**
   * Check that Portal can still access the same repositories
   * Verify that any GitHub Actions integrations continue working
   * Test pull request creation and management features

## Troubleshooting

### Common Migration Issues

**Portal fails to start after configuration change:**

* Verify all GitHub App credentials are correctly entered
* Check that the private key includes proper headers (`-----BEGIN RSA PRIVATE KEY-----`)
* Ensure the GitHub App is installed on your organization

**Repository access issues:**

* Confirm the GitHub App is installed on all required repositories
* Verify repository permissions match your previous PAT scope
* Check that organization permissions are correctly configured

**Authentication errors:**

* Validate Client ID and Client Secret are from the same GitHub App
* Ensure webhook secret matches what was configured in GitHub
* Confirm App ID corresponds to your created GitHub App

### Rollback Procedure

If you need to rollback to PAT authentication:

1. Access **App Settings**
2. Remove the GitHub App configuration from the **apps** section
3. Re-add your PAT in the `token` field
4. Save changes to restore PAT-based authentication

<Info>
  Keep your PAT available during the migration process until you've confirmed
  the GitHub App integration is working correctly.
</Info>

## Next Steps

After successful migration:

* **Remove or rotate your old PAT** for security
* **Document the GitHub App credentials** in your organization's credential management system
* **Update any team documentation** that references the old PAT-based setup
* **Consider setting up GitHub App credential rotation** as part of your security practices

Your Portal instance now benefits from the enhanced security and management capabilities of GitHub App integration!