> ## 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.

# Frequently Asked Questions

> Answers to common questions about bulk catalog ingestion — switching management modes, handling duplicates, re-importing, and more.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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](/portal/guides/events-based-github).
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    ```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
    ---
    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
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="What if I don't see my organization or repository?">
    Check the [Troubleshooting guide](./troubleshooting) 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
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>