Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

You’ve selected Managed by YAML mode. Here’s what happens next as you complete the remaining steps.

​
Step 4: Select Repositories

Choose the repositories you want to ingest. In YAML mode, Portal handles two types of repositories differently: Repositories with catalog-info.yaml:
  • Components defined in the file will be read and registered
  • Multiple components can be defined in one file
Repositories without catalog-info.yaml:
  • Portal will create a Pull Request (or Merge Request for GitLab)
  • The Pull Request includes a generated catalog-info.yaml file
  • Components are registered after the Pull Request is merged
Portal indicates which repositories already have a valid catalog-info.yaml file. Repositories without one will require you to fill in missing details in the next step.

​
Step 5: Fill Missing Details

For repositories without an existing catalog-info.yaml, you must provide:
  • Owner - The team or user responsible for this component
  • Lifecycle - Component stage (production, experimental, deprecated)
  • Type - Component type (service, library, website)
You can fill in these details in bulk for multiple repositories at once. Portal will use this information to generate the catalog-info.yaml file in the Pull Request. This step is required for repositories without YAML. You cannot proceed if required fields are missing.
Catalog Builder Missing Steps
For repositories that already have catalog-info.yaml, Portal uses the existing file and skips this step.

​
Step 6: Review and Complete

Review all components before finalizing. This screen shows:
  • Components from existing catalog-info.yaml files (ready to register)
  • Components that will be added via Pull Request (pending team approval)
  • Any validation warnings for existing YAML files
Click Complete to finish the process.

​
What Happens Next

When you complete the workflow, Portal takes these actions:

​
For Repositories with Existing YAML

  1. Components are immediately registered in the catalog
  2. They appear in Portal within 1-2 minutes
  3. Portal syncs changes when the catalog-info.yaml file is updated

​
For Repositories without YAML

  1. Pull Requests are created in each repository
    • For GitHub/Azure DevOps: “Pull Request”
    • For GitLab: “Merge Request”
  2. Pull Requests include the generated catalog-info.yaml with the metadata you provided
  3. Team members must review and merge the Pull Requests
  4. After merge, Portal registers the components during its next sync
Portal performs scheduled synchronization to detect merged Pull Requests and YAML file changes.

​
Managing Your Components

Since these components are managed by YAML files:
  • Updates are made by editing the catalog-info.yaml file in your repository
  • Changes sync automatically when you commit to the default branch
  • Teams own their component metadata through version control

​
Updating Component Metadata

To update a component:
  1. Edit the catalog-info.yaml file in your repository
  2. Commit and push your changes
  3. Portal syncs the updates automatically
Example catalog-info.yaml: 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: My awesome service
spec:
  type: service
  lifecycle: production
  owner: platform-team

​
Troubleshooting

Having issues? Check the Troubleshooting guide for common problems and solutions, including:
  • Pull Requests not being created
  • Components not appearing after merge
  • Invalid YAML errors