Skip to main content

Frequently Asked Questions

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:

  1. Complete the workflow for your first provider
  2. Open bulk catalog ingestion again and select a different provider
  3. 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.