Getting started with Portal for Backstage
Portal for Backstage brings together your tools, services, documentation, and APIs in one unified developer experience. This guide will help you set up Portal quickly and start unlocking productivity benefits for your engineering teams.
Checklist
- Your Admin password for Portal
- Your Portal License Key
- Access to GitHub
- Admin access to your GitHub organization
- Permission to configure GitHub App with required permissions
Setup Wizard
The first time Portal is started, a Setup Wizard guides you through setting up authentication and determining at least one authorized user.
GitHub Integration Options
You have the choice to enable GitHub integration through two methods:
- GitHub App (Recommended)
- Personal Access Token (PAT)
We recommend using a GitHub App as this provides more granular control over permissions and scope while reducing the risk of orphaned or compromised credentials.
Repository permissions:
| 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 |
| 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:
| Permission | Access Level | Why Required |
|---|---|---|
| Members | Read | Allows Portal to access organization member information for user management and authentication |
Alternative: Using Personal Access Tokens
Personal access tokens are alternative to using passwords for authentication to GitHub.
You can create a personal access token in Settings > Developer settings on GitHub. Make sure the following scopes are selected:
| Scope | Why Required |
|---|---|
| read:user | Allows Portal to read user profile data for authentication and user management |
| read:org | Enables Portal to access organization information and team memberships |
| user:email | Provides access to user email addresses for notifications and identification |
| repo | Grants full control over repositories including read/write access to code, commits, branches, and more |
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.
When creating your OAuth app, use the Homepage URL and Authorization callback URL displayed in the in-app documentation to the right.
Add organizations and administrators
When using a personal access token, a user matching the auth providers username is automatically identified and added as an administrator.
Setup Guide
After completing the Setup Wizard, you'll gain access to the Setup Guide. This comprehensive resource provides:
- A detailed checklist of essential plugins to optimize your Portal experience
- Step-by-step instructions for configuring key features
- Links to additional documentation and guides
- Support resources and troubleshooting tips
- Frequently asked questions to help you get started quickly
The Setup Guide is designed to help you make the most of your Portal for Backstage implementation and ensure you're following best practices from the beginning.
Personalization
When signed in to Portal as an authorized user, you can access the Config Manager at /config-manager. This powerful tool allows you to customize your Portal experience through a user-friendly interface.
The Config Manager provides a comprehensive UI for viewing and updating Portal configuration. It retrieves and updates the configuration stored in Portal using an encrypted PostgreSQL database.
Configuration schemas are automatically detected when the Config Manager loads and then grouped by related plugins into one general configuration page for all similar settings.
For example, the Auth configuration page may consist of multiple auth-related plugins, such as:
@backstage/plugin-auth-backend@backstage/plugin-auth-backend-module-google-provider@backstage/plugin-auth-backend-module-gcp-iap-provider
View and edit configuration
To view or edit configuration for a given plugin:
- Click the "View" button next to the plugin group name on the overview page
- Use the automatically generated web form based on the combined schemas
- Make your desired changes using the appropriate input fields
- Click "Save Changes" to apply your configuration updates
The form automatically renders an appropriate input type based on the type of the field in the schema.
A few specific configuration fields will not be possible to edit. They are marked as read-only by Portal to prevent severe mis-configurations from happening.
Update Company Name
After deploying Portal, one of the first configuration changes you should consider is updating the organization name. This will change the "My Company Catalog" heading on the catalog index page and the page title in your browser tab.
To make this update:
- Navigate to the "App" plugin under "Core plugins" in the Config Manager
- Click on the "View" button
- Locate the "organization" section
- Enter your company's name in the "name" input field
- Click "Save Changes"
Your Portal instance will now display your company name on the catalog index page. 🎉
Add More Authorized Users in Config Manager
Config Manager is integrated with the permission framework and is only accessible by authorized users.
To add a user or group to the list of authorized users:
- Navigate to the "Portal" configuration page on the Config Manager overview page
- Click the "Add Item" button within the "Authorized Users" section
- Fill in the entity reference of the user or group that should be added
- Click "Save Changes" to confirm the addition
Starting and stopping plugins
Most plugins can be enabled or disabled within Portal using a button in the top right.
To stop a plugin:
- Navigate to the plugin's configuration page
- Click the "Stop Plugin" button in the top right
- Confirm your choice when prompted
Stopping a plugin will remove the functionality related to the plugin from Portal. That includes both frontend and backend features.
A plugin that is stopped will appear as "Not running" on the overview page.
To start the plugin again:
- Find the plugin on the overview page
- Click "Start Plugin"
- Wait for the plugin to initialize
Finding configuration
Locating configuration is made easy in Portal using the search box in the Config Manager overview page.
To quickly find specific configuration:
- Enter the name or dot notation path (e.g.
organization.name) in the search box - Review the matching results
- Click on a result to be taken directly to the configuration within the plugin
Onboarding your team
Portal and the Portal Software Catalog provide powerful team management capabilities:
- Makes it easy for one team to manage 10 services
- Scales to support thousands of services across your company
- Provides clear ownership and responsibility tracking
- Enables team-based access control and permissions
- Streamlines onboarding of new team members
The Software Catalog serves as the central system for managing all your software, infrastructure, and resources, making team onboarding and management straightforward and efficient.
Learn more about onboarding teams in the Software Catalog Overview.