Skip to main content

GitHub Integration Troubleshooting

tip

This guide covers common issues and solutions for GitHub integration with Spotify Portal for Backstage, including both GitHub App and Personal Access Token (PAT) authentication methods.

GitHub App Issues​

Installing and Configuring GitHub App​

If you're setting up a GitHub App for the first time or need to reinstall it:

  1. Ensure you have admin access to your GitHub organization
  2. Follow the GitHub App setup process in the Getting Started guide.
  3. Verify you've selected all the required organizations during installation
  4. Confirm the app is installed on all repositories you want to access in Portal
GitHub App Permissions

Managing GitHub App Permissions​

If you're experiencing permission-related issues with your GitHub App:

  1. Check that your GitHub App has all the required permissions for repository access
  2. Verify the organization permissions are set correctly to read members
  3. If permissions were recently updated, you may need to reinstall the app for changes to take effect
GitHub App Permissions

Expired Client Secret or Private Key​

info

GitHub App credentials may need to be regenerated periodically for security reasons. If you're experiencing authentication issues:

  1. Visit your GitHub App settings page in your organization
  2. Check if your Client Secret or Private Key needs to be regenerated
  3. For Client Secret: Click "Generate a new client secret"
  4. For Private Key: Click "Generate a private key"
  5. Update the corresponding credentials in Portal's Config Manager
GitHub App Client Secret
GitHub App Private Keys

Personal Access Token (PAT) Issues​

Replacing GitHub expired personal access token​

info

When your GitHub personal access token expires, you'll need to generate a new one and update it in Portal. Follow these steps:

  1. Visit your GitHub Personal Access Tokens settings
  2. Find your expired token in the list
  3. Click "Regenerate token" to create a new token with the same permissions
GitHub regenerate token interface
info

After regenerating your token:

  1. Set an appropriate expiration date for your security needs
  2. Click "Regenerate token" to confirm
  3. Copy your new token immediately (GitHub will only show it once)
  4. In Spotify Portal, navigate to Config Manager at <baseURL>/config-manager/app#root~1.integrations~1.github__title
  5. Paste your new token in the "token" field
  6. Click "Save Changes" to update your GitHub integration
Config Manager GitHub token field

Insufficient PAT Permissions​

note

If you're experiencing permission issues with your GitHub PAT:

  1. Verify your PAT has all the required scopes
  2. Check if your PAT has expired and needs to be regenerated
  3. Ensure the GitHub user associated with the PAT has appropriate access to the repositories

Organization Access Issues​

Missing Teams or Organizations​

If you can't see certain GitHub teams or organizations in Portal:

  1. Verify the GitHub App is installed on those organizations or your PAT has access to them
  2. Check that the organizations are included in your Portal configuration
  3. Ensure the GitHub App or PAT has the necessary permissions to read organization data
  4. Try refreshing the catalog to trigger a new sync with GitHub

Rate Limiting​

info

If you're experiencing rate limiting issues with GitHub API:

  1. Consider switching from PAT to GitHub App authentication (which has higher rate limits)
  2. Optimize your catalog refresh intervals to reduce API calls
  3. See the Rate Limiting guide for more detailed solutions

Migrating from PAT to GitHub App​

For improved security and higher rate limits, we recommend migrating from Personal Access Tokens to GitHub Apps.

You can find more information about GitHub Apps in the Getting Started guide.