sthings-backstage

[An Internal Developer Portal] - built on Backstage for stuttgart-things.

Overview

sthings-backstage provides a centralized platform for managing software development across the organization, featuring:

• Software Catalog - Centralized registry for services and components
• TechDocs - Technical documentation managed as code
• Software Templates - Scaffolding system for creating new projects
• Kubernetes Integration - Visibility and management of Kubernetes clusters
• GitHub Integration - Authentication, catalog import, and scaffolder actions
• GitHub Scaffolder Module - Extended GitHub actions for software templates
• Claim Machinery Plugin - Integration with Claim Machinery API for dynamic claim templates
• Claim Registry Plugin - Scaffolder extensions for browsing and deleting claims via GitHub PRs
• YAML Utils Module - Scaffolder action for parsing workspace YAML files in template workflows
• GitHub Actions Plugin - CI/CD visibility for GitHub Actions workflow runs on entity pages
• Unified Search - Cross-entity search functionality

Getting Started

Prerequisites: Node.js 22 or 24, Yarn 4.13.0

yarn install
yarn dev

This starts the frontend on port 3000 and backend on port 7007.

Project Structure

sthings-backstage/
├── packages/app/       # Frontend React application
├── packages/backend/   # Backend Node.js API
├── plugins/            # Custom plugins directory
├── app-config.yaml     # Main configuration
└── catalog-info.yaml   # Catalog entity definitions

Tasks

This project uses Task for automation. Run task --list to see all available tasks.

Task	Description
task dev	Start Backstage in development mode with .env loaded
task build-push-scan-image	Build, push, and scan container image using Dagger
task do	Interactive task selector (requires gum)

Included task modules:

Prefix	Source
init:	Backstage initialization tasks
git:	Git operations
docker:	Docker build tasks
trivy:	Container security scanning

Documentation

See the docs folder for detailed documentation:

• Configuration - Environment variables and secrets
• GitHub Integration - OAuth and API setup
• GitHub Scaffolder Module - Extended GitHub actions for templates
• Scaffolding - Project templates and structure
• Claim Machinery Plugin - Installation and configuration guide
• Claim Registry Plugin - Claim browsing and deletion via GitHub PRs
• YAML Utils Module - Scaffolder action for parsing YAML files
• GitHub Actions Plugin - CI/CD workflow visibility on entity pages

Claim Machinery Plugin

This instance includes the backstage-claim-machinery-plugin which provides custom scaffolder extensions for rendering Kubernetes claim manifests via the Claim Machinery API.

Components

Component	Location	Purpose
Backend Action	packages/backend/src/plugins/scaffolder-claim-machinery/	claim-machinery:render scaffolder action
Field Extensions	packages/app/src/scaffolder/	ClaimMachineryPicker and ClaimMachineryParameters UI components

Configuration

# app-config.yaml
claimMachinery:
  apiUrl: ${CLAIM_MACHINERY_API_URL}

proxy:
  endpoints:
    '/claim-machinery':
      target: ${CLAIM_MACHINERY_API_URL}
      changeOrigin: true

Environment Variables

Variable	Description
CLAIM_MACHINERY_API_URL	URL of the Claim Machinery API

For complete installation and usage details, see the Claim Machinery Plugin documentation.

Claim Registry Plugin

This instance includes the backstage-claim-registry-plugin which provides a scaffolder field extension for browsing claims from the Machinery Registry API and a backend action for deleting claims via GitHub pull requests.

Components

Component	Location	Purpose
Backend Action	packages/backend/src/plugins/scaffolder-claim-registry/	claim-registry:delete scaffolder action
Field Extension	packages/app/src/scaffolder/	RegistryClaimPicker UI component

Configuration

# app-config.yaml
proxy:
  endpoints:
    '/machinery-registry':
      target: ${CLAIM_MACHINERY_API_URL}
      changeOrigin: true

Environment Variables

Variable	Description
CLAIM_MACHINERY_API_URL	URL of the Machinery Registry API
GITHUB_TOKEN	GitHub PAT for creating deletion PRs

For complete installation and usage details, see the Claim Registry Plugin documentation.

YAML Utils Module

The utils:yaml:parse scaffolder action reads and parses YAML files from the scaffolder workspace. This enables append-mode templates that fetch existing configuration from a repository, merge new entries, and create a PR with the combined result.

Components

Component	Location	Purpose
Backend Action	packages/backend/src/plugins/scaffolder-yaml-utils/	utils:yaml:parse scaffolder action

Key Features

• Reads YAML files from the scaffolder workspace and outputs parsed content
• Graceful error handling: returns {} for missing or invalid files
• Designed for use with fetch:plain to enable merge/append workflows

For complete details, see the YAML Utils Module documentation.

GitHub Actions Plugin

The CI/CD tab on service and website entity pages displays GitHub Actions workflow runs for the associated repository.

Components

Component	Location	Purpose
Frontend Plugin	@backstage-community/plugin-github-actions	EntityGithubActionsContent on CI/CD tab
Entity Page Integration	packages/app/src/components/catalog/EntityPage.tsx	Conditional rendering via isGithubActionsAvailable

Required Annotation

Catalog entities must have the github.com/project-slug annotation to enable the CI/CD tab:

metadata:
  annotations:
    github.com/project-slug: 'org/repo-name'

For complete details, see the GitHub Actions Plugin documentation.

Known Upgrade Constraints

React 19

React 19 upgrade is blocked by upstream Backstage dependencies (as of April 2026). Key blockers:

Dependency	Issue	Status
@material-ui/core (MUI v4)	Uses ReactDOM.findDOMNode(), removed in React 19	Waiting on Backstage MUI v5 migration
@graphiql/react@0.29.0	Uses unmountComponentAtNode, removed in React 19. Newer versions (0.37+) have breaking API changes incompatible with @backstage/plugin-api-docs	Waiting on @backstage/plugin-api-docs update
react-markdown@8.0.7	TypeScript type errors with @types/react@19	Fixable via resolution to ^10.1.0, but moot given the above

Action: Revisit once Backstage officially supports React 19 and completes the MUI v5 migration. Track progress in the Backstage MUI v5 migration issue.