Introducing Gitpod's Backstage plugin
Pauline Narvas
DevRel + Community at Gitpod
Apr 23, 2024
Internal developer portals are a popular part of the platform engineering toolkit. Internal developer portals like Backstage act as an entry point to an organization’s internal platform, providing a central place for new joiners to get oriented and for developers to explore internal platform services.
The goal is for our developers to spend less time “finding things”, and more time delivering business value. However, portals are not without their limitations…
A core challenge of portals is how they are rarely the “source of truth”. What this means is that when developers visit a portal they can find some information. But, when it comes to developers “taking the next step” they now have to leave the internal developer portal, go back to their laptop, login to systems or download packages just to get started.
At best, leaving the portal is mildly annoying. But, at worst, it can lead to significant impact on portal adoption. And adoption challenges are a big focus across the Backstage community, as The New Stack reports Backstage adoption is at 10%, and recent Backstage roadmap efforts are focused on driving adoption.
Is it because portals “don’t work”? No. It’s because we’re often not solving enough of the problem for our developers.
And, that’s where Cloud Development Environments (CDEs) can help. CDEs can be started with a single click, or even a URL link. Developers are then dropped into a fully running development environment configured with all the tooling developers need to be ready-to-code, where even their authentication flow can be entirely configured.
When combined with a CDE, internal developer portals become supercharged.
For instance, during the design phase of a feature, when a developer is exploring another team’s API surface, they can go to Backstage to see the API spec, but also launch a full environment to explore, and build out a proof-of-concept to help inform their investigation.
Or, when an SRE needs to start an application they’ve never worked on before during a severity 1 incident. They skip setting environment variables and changing package versions, diving straight into a development environment to debug and fix issues.
The more we support our developers to solve end-to-end flows, the better our internal portal adoption can be, and ultimately the faster we get to our developer experience goals. Because internal developer portals and CDEs are such a great match, we’ve created a Gitpod plugin to make it even easier to compose these two tools together.
Gitpod ❤️ Backstage
So, how does the Gitpod plugin work?
A core component of Backstage is the software catalog—a system that aggregates your organization’s software assets and tooling, acting as a single source of truth for your engineering landscape.
The Backstage catalog is defined via catalog metadata files that are (typically) stored in your repositories. This metadata can include information about the software’s lifecycle, ownership details, and links to the source code and documentation. Integration with Gitpod in Backstage can be configured through minimal modifications to the catalog file, and (optional) installation of an NPM plugin.
For example:
ymlapiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: spring-petclinic
description: 'A sample Spring-based Java application built to manage a pet clinic.'
annotations:
github.com/project-slug: gitpod-samples/spring-petclinic
spec:
type: service
lifecycle: production
owner: gitpod
system: petclinic-systemThe Gitpod plugin adds an ”Open in Gitpod” button to your Backstage application, using the metadata from your project’s catalog entity to construct a Gitpod URL.
The Gitpod URL points to an SCM repository, where a .gitpod.yml is configured (at the directory root), to instruct Gitpod how to create the development environment, such as the packages and editor extensions to install.
New to Gitpod? Get started with our tutorial.
Installation
Add the Gitpod Backstage Plugin to your Backstage app by running:
bashyarn add --cwd packages/app @gitpod-io/backstage-plugin-gitpodImport and use the GitpodButton component in your app, typically where you display information about your services or components. For example, in EntityPage.tsx:
tsximport { GitpodButton } from '@gitpod-io/backstage-plugin-gitpod';
//....
const HomePage = () => (
// ...
<Grid item md={3} xs={6}>
<GitpodButton />
</Grid> // ...
);In our Backstage demo, we’ve implemented it in the Overview Content component:
tsxconst overviewContent = (
<Grid container spacing={3} alignItems="stretch">
{entityWarningContent}
<Grid item md={6}>
<EntityAboutCard variant="gridItem" />
</Grid>
<Grid item md={6}>
**
<GitpodButton />
**
</Grid>
<Grid item md={6} xs={12}>
<EntityCatalogGraphCard variant="gridItem" height={400} />
</Grid>
<Grid item md={4} xs={12}>
<EntityLinksCard />
</Grid>
<Grid item md={8} xs={12}>
<EntityHasSubcomponentsCard variant="gridItem" />
</Grid>
</Grid>
);Integrating Gitpod through a metadata link in the catalog file
The above method requires you to actually install an npm package into the Backstage instance itself, which may not be simple or easy if you’re not on the Backstage team that owns the instance.
If you simply want to see how Gitpod could fit into your Backstage flow, for a very straightforward approach, you can directly integrate Gitpod functionality by adding a specific metadata entry to your Backstage catalog entity file.
This method leverages the Gitpod URL scheme to open repositories in Gitpod, without the need to install the plugin, or include an explicit UI component in Backstage:
ymlapiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: example-website
annotations:
gitpod.io/host: gitpod.io
github.com/project-slug: backstage/backstage
links:
- url: https://gitpod.io/#<https://your-repo-link>
title: Open In Gitpod
icon: dashboard
spec:
type: website
lifecycle: experimental
owner: guests
system: examples
providesApis: [example-grpc-api]"Replace <https://your-repo-link> with the actual URL of your GitHub/GitLab/Bitbucket repository.
Now, whenever users view the service or component in Backstage, they can use the link in the Backstage interface to open the repository in Gitpod directly, without any additional setup like installing the plugin.
This link approach is a great way to explore the benefits of using a CDE, in a very minimal way. With Gitpod, you have 50 hours for free each month to explore how Gitpod works, and explore how it could support your Backstage efforts.
Contribute
If you have any feature requests, leave an issue or raise a pull request, we welcome contributions!
Learn more
Pauline Narvas
DevRel + Community at Gitpod
Publish date
Apr 23, 2024
