This tutorial will guide you through the steps required to set Roadie up for basic use within your organization. Once completed, you will:
- Be an admin user of Roadie.
- Have connected Roadie to your organization’s GitHub account.
There are 3 kinds of Backstage resource used in this tutorial.
Userentity represents an employee at your company.
Groupentity represents a team or larger organizational structure.
Componententity represents a piece of software like a website or backend service.
In order to complete this guide, you will need the following things:
- Access to a Roadie account. If you do not yet have access, please join the waiting list.
- A GitHub Cloud or GitHub Enterprise Cloud account.
- A test service on GitHub which you can make changes to.
Roadie needs 2 connections to GitHub in order to function.
- A Personal Access Token to access the YAML metadata files that Backstage needs to operate.
- An OAuth client ID and secret so that your user can make requests from the browser to the GitHub API.
Use the steps below to create a client ID and secret and Personal Access Token (PAT) for Roadie.
If you wish to tightly restrict the access that Roadie has, perhaps for evaluation purposes, please follow this guide.
Visit the developer settings of your GitHub account and create a PAT which has the scopes
The official GitHub docs for creating a Personal Access Token are here.
⚠️ The token’s owner must be a member of the organization, rather than an outside collaborator or other relation.
Want to use a token with more restrictive scopes? Use this guide.
Visit the Developer Settings of your GitHub organization account. Click “New OAuth App”.
Fill out the following information in the form. ⚠️ Be sure to replace
your-company with your Roadie subdomain.
|Application name||Roadie Backstage|
|Application description||Backstage service catalog and developer UI provided by https://roadie.io|
|Authorization Callback URL||
Click “Register Application” and then “Generate a new client secret”.
Take a note of the client ID and the generated client Secret. You will need these in the next step.
Visit the Secrets management interface on Roadie Backstage at
GITHUB_TOKEN field. Click the Pencil Icon to edit the field.
Enter the PAT into the input and click the Save button.
Do the same thing for the
Wait until Roadie has activated the token before proceeding.
Roadie admins have special powers such as the ability to add and remove Backstage plugins. We will use GitHub teams to create an admin group for Roadie.
ℹ️ Admin groups are not a security measure. They hide certain UX features from regular users in order to simplify the experience. Backstage does not currently support role based access control (RBAC).
Visit GitHub Teams in your organization’s GitHub account and click the New Team button.
Set the Team name to
roadie-backstage-admin. This is a special value and must be an exact match.
Enter a Description such as “Users with Backstage administration abilities.”.
Leave Parent team unselected and click the Create team button.
By default, GitHub adds your account to the team as a member. You are now an admin on Roadie and should have access to two main features:
- Access to the Secrets panel via the “Administration” link in the sidebar.
- The ability to add and remove plugin cards and tabs (see red-circled icons).
ℹ️ It can take some time for Roadie to refresh the list of teams from GitHub teams. If you do not see admin functions immediately, please wait a few minutes and try again.
Let’s add a component to Backstage.