Backstage Plugin

A Backstage frontend plugin to sync Backstage systems to StackGen.

Published to npmjs.org as @stackgenhq/backstage-plugin-stackgen. Install works without a GitHub PAT. Release process: docs/PUBLISH.md.

Setup

1. Install this plugin in your Backstage frontend:

   yarn --cwd packages/app add @stackgenhq/backstage-plugin-stackgen

   No .yarnrc.yml GitHub Packages scope is required if you install from npmjs. The same version is also published to GitHub Packages.

2. Modify the following files in your Backstage frontend app:

   • /packages/app/src/App.tsx

     ...
     // Add this in imports
     import { StackGenPage } from '@stackgenhq/backstage-plugin-stackgen';
     ...
     
     ...
     // Add this in the routes
     <Route path="/stackgen" element={<StackGenPage />} />
     ...

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

     ...
     import { StackGenIcon } from '@stackgenhq/backstage-plugin-stackgen';
     ...
     
     ...
     // Add Stackgen sidebar item
     <SidebarItem icon={StackGenIcon} to="stackgen" text="StackGen"/>
     ...

3. the plugin requires @stackgenhq/backstage-plugin-stackgen-backend so ensure it is installed and configured in Backstage backend.

Field Extensions

The plugin provides field extensions that can be used in your Backstage scaffolder templates.

Scope id: prefer projectId (StackGen project UUID). Deprecated aliases teamId / orgId still work in ui:options and proxy queries. Prefer ProjectSelect; TeamSelect is a deprecated alias of the same field.

ProjectSelect Extension

Project selection dropdown. Fetches allowed projects from StackGen (/v1/allowed-teams). TeamSelect is a deprecated alias.

AppStackSelect Extension

AppStack selection dropdown. Filters by ui:options.projectId when set; otherwise lists all available AppStacks.

TemplateAppStackSelect Extension

A field extension that lists tenant-wide StackGen template AppStacks for selection.

VaultSecretSelect Extension

Lists StackGen vault secrets (optionally scoped by projectId and category).

ExporterGitConfigSelect Extension

Lists appstack-scoped git exporter configs. Wire ui:options.projectId and ui:options.appstackName to form field names. Auto-selects when exactly one config exists and shows helper text for bootstrap vs selection outcomes.

ExporterBaseBranch Extension

Prefills the base branch from the selected exporter config (parameters.target_branch). Wire ui:options.projectId and ui:options.configId. Does not overwrite after the user edits until the config selection changes.

ExporterPushBranch Extension

Object field { branch, useSameBranch }. Prefills branch from the latest export history head and sets useSameBranch: true when left unchanged; user edits set useSameBranch: false. Wire ui:options.projectId and ui:options.appstackName.

EnvironmentSelect Extension

Single-select environment profile picker with a color dot + profile name. Proxies getAllEnvProfiles (same as appcd-ui).

UserGroupSelect Extension

Multi-select combining StackGen users and user groups in one control (listUsers + listUserGroups).

Optional ui:options:

• lockCurrentUser (default true) — keep the current StackGen user selected and non-removable
• userFilterRegex — keep users whose email (or name) matches; e.g. "@example\\.com$"
• groupFilterRegex — keep groups whose name matches; e.g. "^platform-"

ModuleSelect Extension

Multi-select of catalog modules with label (version) options (getAccessibleCustomResourceTemplates).

VariableSelect Extension

Pick a topology TF variable, enter a value, and accumulate { name, value } pairs (getTFVariables). Requires topologyId.

Adding Field Extensions to Backstage Frontend

To use these field extensions in your Backstage frontend, you need to add them to your App.tsx file:

1. Add the field extensions to your scaffolder route in /packages/app/src/App.tsx:

import {
  ProjectSelectFieldExtension,
  AppStackNameFieldExtension,
  TemplateAppStackSelectFieldExtension,
  VaultSecretSelectFieldExtension,
  ExporterGitConfigSelectFieldExtension,
  ExporterBaseBranchFieldExtension,
  ExporterPushBranchFieldExtension,
  EnvironmentSelectFieldExtension,
  UserGroupSelectFieldExtension,
  ModuleSelectFieldExtension,
  VariableSelectFieldExtension,
} from '@stackgenhq/backstage-plugin-stackgen';

// In the routes configuration
<Route path="/create" element={<ScaffolderPage />}>
  <ScaffolderFieldExtensions>
    <ProjectSelectFieldExtension />
    <AppStackNameFieldExtension />
    <TemplateAppStackSelectFieldExtension />
    <VaultSecretSelectFieldExtension />
    <ExporterGitConfigSelectFieldExtension />
    <ExporterBaseBranchFieldExtension />
    <ExporterPushBranchFieldExtension />
    <EnvironmentSelectFieldExtension />
    <UserGroupSelectFieldExtension />
    <ModuleSelectFieldExtension />
    <VariableSelectFieldExtension />
  </ScaffolderFieldExtensions>
</Route>

3. You can now use these field extensions in your scaffolder templates:

# Example usage in scaffolder template
fields:
  - name: projectId
    type: string
    ui:field: ProjectSelect

  - name: appstack
    type: string
    ui:field: AppStackSelect
    ui:options:
      projectId: projectId  # Optional form field or UUID. Omit to list all AppStacks

  - name: templateAppstackId
    type: string
    ui:field: TemplateAppStackSelect

  - name: vaultReference
    type: string
    ui:field: VaultSecretSelect
    ui:options:
      projectId: projectId # Optional form field or UUID. Omit for enterprise (shared) secrets
      # projectId: a61a485a-d4ba-425d-ab69-b6fc2b647c5b # static UUID also works
      category: scm # Optional: filter based on category
      subcategory: github # Optional: filter based on subcategory

  - name: existingExporterConfigId
    type: string
    ui:field: ExporterGitConfigSelect
    ui:options:
      projectId: projectId
      appstackName: appstack

  - name: baseBranch
    type: string
    ui:field: ExporterBaseBranch
    ui:options:
      projectId: projectId
      configId: existingExporterConfigId

  - name: pushBranch
    type: object
    ui:field: ExporterPushBranch
    ui:options:
      projectId: projectId
      appstackName: appstack

  - name: environmentId
    type: string
    ui:field: EnvironmentSelect
    ui:options:
      projectId: projectId  # optional form field or UUID
      topologyId: topology  # optional form field or UUID

  - name: members
    type: array
    ui:field: UserGroupSelect
    ui:options:
      projectId: projectId  # optional

  - name: modules
    type: array
    ui:field: ModuleSelect
    ui:options:
      projectId: projectId  # optional project scope

  - name: variableValues
    type: array
    ui:field: VariableSelect
    ui:options:
      topologyId: topology  # required form field or UUID
      projectId: projectId  # optional

Note: ui:options.projectId on AppStackSelect is optional. Prefer projectId over deprecated teamId / orgId aliases.

Sample templates

Shipped under templates/ in the backend plugin (also copied into stackgen-backstage/examples/template/):

| Template | Flow | Fields / actions | |----------|------|------------------| | project-with-members | Create project → add members | UserGroupSelect, stackGen:assignProjectMembers | | appstack-with-modules | Create AppStack with catalog modules | ProjectSelect, ModuleSelect, stackGen:createAppStack | | appstack-configure-environment | Set TF var values on an existing env | ProjectSelect, AppStackSelect, EnvironmentSelect, VariableSelect, stackGen:setEnvironmentVariableValues |

Running Locally

1. Run yarn install.
2. Set backend.baseUrl in app-config.yaml to where your Backstage backend is running and add the proxy configuration in your backend.
3. Run yarn start.