https://github.com/stuttgart-things/sthings-backstage
suttgart-things backstage app
https://github.com/stuttgart-things/sthings-backstage
backstage idp-platform platform-engineering portal
Last synced: 2 months ago
JSON representation
suttgart-things backstage app
- Host: GitHub
- URL: https://github.com/stuttgart-things/sthings-backstage
- Owner: stuttgart-things
- License: apache-2.0
- Created: 2026-01-22T13:37:44.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-04-07T09:59:53.000Z (4 months ago)
- Last Synced: 2026-04-07T11:33:39.033Z (4 months ago)
- Topics: backstage, idp-platform, platform-engineering, portal
- Language: TypeScript
- Homepage:
- Size: 2.87 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```sh
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](https://taskfile.dev) 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](docs/) folder for detailed documentation:
- [Configuration](docs/configuration.md) - Environment variables and secrets
- [GitHub Integration](docs/github-integration.md) - OAuth and API setup
- [GitHub Scaffolder Module](docs/github-scaffolder-module.md) - Extended GitHub actions for templates
- [Scaffolding](docs/scaffolding.md) - Project templates and structure
- [Claim Machinery Plugin](docs/claim-machinery-plugin.md) - Installation and configuration guide
- [Claim Registry Plugin](docs/claim-registry-plugin.md) - Claim browsing and deletion via GitHub PRs
- [YAML Utils Module](docs/yaml-utils-module.md) - Scaffolder action for parsing YAML files
- [GitHub Actions Plugin](docs/github-actions-plugin.md) - 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
```yaml
# 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](docs/claim-machinery-plugin.md).
## 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
```yaml
# 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](docs/claim-registry-plugin.md).
## 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](docs/yaml-utils-module.md).
## 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:
```yaml
metadata:
annotations:
github.com/project-slug: 'org/repo-name'
```
For complete details, see the [GitHub Actions Plugin documentation](docs/github-actions-plugin.md).
## 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](https://github.com/backstage/backstage/issues/20447).