Frequently Asked Questions - Spotify for Backstage

Can I switch between Portal and YAML management modes later?

Each new ingestion can use a different mode. Every time you run bulk catalog ingestion, you choose the management mode for that batch of repositories. You can freely mix Portal-managed and YAML-managed components in your catalog.For existing components: Switching the management mode of already-ingested components requires unregistering them and re-importing with the desired mode:

Portal to YAML: Unregister components, then use bulk catalog ingestion to re-import in YAML mode. Pull Requests will be created with catalog-info.yaml files.
YAML to Portal: Unregister components (and optionally delete the catalog-info.yaml files), then re-import in Portal mode.

We recommend choosing the right mode initially to avoid this migration process for existing components.

What happens if I select a repository that's already in the catalog?

Bulk catalog ingestion typically won’t show repositories that are already registered. If you need to update an existing component:

Managed by Portal mode: Update it through the Portal UI
Managed by YAML mode: Edit the catalog-info.yaml file in the repository

Can I use bulk catalog ingestion with multiple providers simultaneously?

Not in a single workflow. Each ingestion session works with one provider at a time. To ingest from multiple providers:

Complete the workflow for your first provider
Open bulk catalog ingestion again and select a different provider
Repeat as needed for each provider

What fields are auto-detected vs. required manual input?

Auto-detected fields:

Component name (from repository name)
Description (from repository description, if available)
Repository URL and metadata

Typically require manual input:

Owner (Portal tries to detect from CODEOWNERS, but often needs manual specification)
Lifecycle (defaults to “unknown” if not provided)
Type (defaults to “unknown” if not provided)

How often does the catalog sync with catalog-info.yaml files?

For YAML mode components:

Scheduled sync: Portal runs periodic synchronization (frequency varies by configuration)
Manual refresh: You can trigger a refresh from the component page in Portal
Webhook-based: Some setups support real-time updates via webhooks

Read more about events based ingestion.

Can I bulk-edit components after ingestion?

Managed by Portal mode: Yes, you can select multiple components in the catalog and update shared fields through the Portal UI.Managed by YAML mode: Bulk editing requires updating multiple catalog-info.yaml files. You can:

Write a script to update files across repositories
Manually edit each file
Use find-and-replace tools in your code editor

What happens if my Pull Request is rejected or modified before merge?

If your YAML mode Pull Request is:Rejected/Closed: The component won’t be registered. You can:

Manually create the catalog-info.yaml file
Work with the repository team to resolve concerns

Modified before merge: Portal will use the final merged version of the catalog-info.yaml. Any changes made during Pull Request review will be reflected in the registered component.

Do I need special permissions to use bulk catalog ingestion?

Permission requirements vary by Portal instance configuration, but typically:To use bulk catalog ingestion:

Admin Access to Portal
Read access to the source control provider

For Managed by Portal mode:

Admin permissions to create catalog entities

For Managed by YAML mode:

Portal must have write access to repositories (configured at admin level)
You may need approval from repository owners to merge Pull Requests

Contact your Portal administrator about specific permission requirements.

Can one repository create multiple components?

Managed by Portal mode: No. Each repository becomes exactly one component (1:1 mapping).Managed by YAML mode: Yes. Your catalog-info.yaml can define multiple components by including multiple entity definitions:

---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: frontend
spec:
  type: website
  lifecycle: production
  owner: platform-team
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: backend
spec:
  type: service
  lifecycle: production
  owner: platform-team

Where can I see my Managed by Portal components?

You can find your Managed by Portal components in the catalog page. Use the Managed By filter to show only Portal-managed components or YAML-managed components.

What if I don't see my organization or repository?

Check the Troubleshooting guide for detailed solutions. Common causes include:

Provider credentials lack necessary permissions
Organizations/repositories are private without proper access
Items are already registered in the catalog

Can I preview what will be created before completing the workflow?

Yes! Step 6 (Review) shows exactly what components will be created or what Pull Requests will be generated. Review this carefully before clicking Complete.

Documentation Index