Skip to main content

YAML Mode Walkthrough

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