Migrating to a GitHub App Integration

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 the Portal Config Manager
• 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, which includes:

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

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

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

Security Note

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

3. Update Portal Configuration

Now migrate your Portal configuration from PAT to GitHub App:

1. Access Config Manager

   • Navigate to /config-manager/app#root~1.integrations~1.github__title
   • Or go to Config Manager → App → 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 Config Manager
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

note

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

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!