Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
Spacelift.io logo

Backstage Spacelift.io Plugin

Created by Spacelift.io

Spacelift.io is a platform that helps you run infrastructure as code. It brings policy, visibility, and control to the workflows your teams already use.

The Backstage plugin connects your self hosted portal to Spacelift. It adds a page where you can see your stacks with status and recent runs. You can open a stack in Spacelift with one click. Where allowed, you can start a rerun without leaving Backstage. This puts day to day IaC activity in the same place your teams manage services and docs.

For engineers, the value is focus. During an incident, you can check stack health and the last changes from the portal. For routine work, you can review runs, watch progress, and jump to details only when needed. Platform teams get a shared view across spaces and projects, using the access that the Spacelift API key permits. That keeps control in one place while cutting tool switching.

At a high level, the plugin shows the stacks that the configured key can see. It surfaces status and run history, and offers quick actions when the stack allows it. Backstage remains your hub. Spacelift stays the system of record for IaC state and execution.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the backend plugin with the new backend system

  1. Add the backend package

    Copy 
    # From your Backstage root directory
yarn --cwd packages/backend add @spacelift-io/backstage-integration-backend

  2. Register the backend plugin

    In packages/backend/src/index.ts

    Copy 
    // packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

backend.add(import('@spacelift-io/backstage-integration-backend'));

await backend.start();

  3. Add configuration

    In app-config.yaml

    Copy 
    spacelift:
  hostUrl: '<your-subdomain>.app.spacelift.io'
  apiKey: ${SPACELIFT_API_KEY}
  apiSecret: ${SPACELIFT_API_SECRET}

    Replace the subdomain placeholder with your Spacelift address without https. Keep the API values in environment variables.

Install the backend plugin with the old backend system

This plugin targets the new backend system that uses createBackend. It does not document a legacy router. If your app still uses the legacy backend, migrate to the new backend system before installing this plugin.

Install the frontend plugin

  1. Add the frontend package

    Copy 
    # From your Backstage root directory
yarn --cwd packages/app add @spacelift-io/backstage-integration-frontend

  2. Add the route so users can view the page

    In packages/app/src/App.tsx

    Copy 
    // packages/app/src/App.tsx
import { SpaceliftIoPage } from '@spacelift-io/backstage-integration-frontend';
// other imports already present in your App

const routes = (
  <FlatRoutes>
    {/* other routes */}
    <Route path="/spacelift" element={<SpaceliftIoPage />} />
  </FlatRoutes>
);

  3. Add the sidebar item so users can navigate to it

    In packages/app/src/components/Root/Root.tsx

    Copy 
    // packages/app/src/components/Root/Root.tsx
import SpaceliftIcon from '@material-ui/icons/CloudQueue';
// other imports already present in your Root

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
      {/* other sidebar items */}
      <SidebarItem icon={SpaceliftIcon} to="spacelift" text="Spacelift" />
    </Sidebar>
    {children}
  </SidebarPage>
);

  4. Ensure frontend config includes the host value

    In app-config.yaml

    Copy 
    spacelift:
  hostUrl: '<your-subdomain>.app.spacelift.io'

Environment variables

Set the API key values for the backend

Copy 
export SPACELIFT_API_KEY="your-api-key-id"
export SPACELIFT_API_SECRET="your-api-key-secret"

You can place these in your Backstage process environment or your deployment environment.

Where the page shows up

  • The page is available at the path /spacelift in your app
  • The sidebar entry named Spacelift links to it

Permissions behavior

The backend uses the Spacelift API key you configure. The plugin does not add user level permissions. Limit access to this page using your Backstage permission setup. Keep the API key scoped to the minimum needed in Spacelift.

Compatibility

  • Backend requires @backstage/backend-plugin-api version 1.3.0 or newer
  • Frontend requires @backstage/core-components version 0.17.1 or newer
  • Use Backstage 1.17.0 or newer for best results

Changelog

This changelog is produced from commits made to the Spacelift.io plugin since 5 months ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

None

Features

  • Add backend plugin with deployment scripts #1 merged 4 months ago
  • Add frontend plugin #3 merged 4 months ago

Documentation

  • Add architecture design schema. Add project structure docs. Fix links to Spacelift docs and npm page references #9 merged 4 months ago
  • Update README files to use new npm org naming. Fix license inconsistency in README #8 merged 4 months ago
  • Update README files #6 merged 4 months ago

Tests

  • Add backend tests #2 merged 4 months ago
  • Add frontend tests #4 merged 4 months ago

CI

  • Improve publish workflow #7 merged 4 months ago
  • Add CI checks for tests #2 merged 4 months ago

Internal

  • Migrate types to a common project for reuse by frontend #2 merged 4 months ago

Set up Backstage in minutes with Roadie

Get a demo