GitHub Identity Setup Guide

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.

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.

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:

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

Organization permissions:

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

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

tip

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

Screenshot needed: Catalog page showing updated organization name

---

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)

Screenshot needed: Auth providers list showing available options

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"

Important

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

---

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"

Screenshot needed: GitHub integration configuration form

Validation Tip

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

Screenshot needed: Successfully configured GitHub integration

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"

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"

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.

---

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"

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.

---

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

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.

---

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