←  back to blog
Introducing Gitpod's Backstage plugin

Introducing Gitpod's Backstage plugin

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.

Gitpod's Backstage plugin

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:

language icon yml
apiVersion: backstage.io/v1alpha1
kind: Component
  name: spring-petclinic
  description: 'A sample Spring-based Java application built to manage a pet clinic.'
    github.com/project-slug: gitpod-samples/spring-petclinic
  type: service
  lifecycle: production
  owner: gitpod
  system: petclinic-system

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

Gitpod Backstage demo

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.


Add the Gitpod Backstage Plugin to your Backstage app by running:

language icon bash
yarn add --cwd packages/app @gitpod-io/backstage-plugin-gitpod

Import and use the GitpodButton component in your app, typically where you display information about your services or components. For example, in EntityPage.tsx:

language icon tsx
import { 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:

language icon tsx
const overviewContent = (
	<Grid container spacing={3} alignItems="stretch">
		   <Grid item md={6}>
			<EntityAboutCard variant="gridItem" />
		<Grid item md={6}>
			<GitpodButton />
		<Grid item md={6} xs={12}>
			<EntityCatalogGraphCard variant="gridItem" height={400} />
		<Grid item md={4} xs={12}>
			<EntityLinksCard />
		<Grid item md={8} xs={12}>
			<EntityHasSubcomponentsCard variant="gridItem" />

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:

language icon yml
apiVersion: backstage.io/v1alpha1
kind: Component
  name: example-website
    gitpod.io/host: gitpod.io
    github.com/project-slug: backstage/backstage
    - url: https://gitpod.io/#<https://your-repo-link>
      title: Open In Gitpod
      icon: dashboard
  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.

alt text

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.


If you have any feature requests, leave an issue or raise a pull request, we welcome contributions!

Learn more

Join developers, everywhere.

Development environments pre-configured with the tools and dependencies needed to get inspired and start building.

Monthly Newsletter

Subscribe to get a summary of what we've shipped over the last month, plus everything you need to know around developer experience.

By submitting this, I confirm that I have read and understood the Privacy policy.

Related articles