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

# Understanding Management Modes

> Compare Portal-managed and YAML-managed modes for catalog components — how metadata is stored, updated, and when to use each approach.

When using bulk catalog ingestion, you choose how component metadata will be managed for each ingestion batch. This affects how you update component information, where data is stored, and your team's workflow.

## The Two Modes

### Managed by Portal

Components are created and maintained entirely within Portal. No `catalog-info.yaml` file is required in your repositories.

**How it works:**

* Each repository becomes one component (1:1 mapping)
* Portal attempts to detect metadata like owner from your repository
* Any existing `catalog-info.yaml` files are ignored
* All component data lives in Portal's database
* Updates are made using edit and bulk edit dialogs

**When to use:**

* You want to get up and running quickly
* You don't want to coordinate Pull Request approvals across teams
* You prefer centralized component management
* Your teams aren't familiar with YAML or Portal entity formats
* You have many repositories to onboard at once
* Your organization prefers centralized management
* You want minimal friction for teams

### Managed by YAML

Component metadata lives in source-controlled `catalog-info.yaml` files within your repositories. Portal reads these files and syncs changes automatically.

**How it works:**

* Portal looks for valid `catalog-info.yaml` files in repositories
* For repositories with existing files: components are immediately registered
* For repositories without files: Portal creates a Pull Request with a generated `catalog-info.yaml`
* Once Pull Requests are merged, Portal syncs the components
* Updates to the YAML file automatically update the catalog
* One repository can define multiple components

**When to use:**

* Your team already uses catalog-info.yaml files
* You want version-controlled component metadata
* Your team is comfortable with YAML and Git workflows
* You want components to be owned and updated by repository teams
* You need to define multiple components per repository
* You want audit trails for metadata changes
* Teams should own their component definitions
* Source control is important for your compliance

## Side-by-Side Comparison

<AccordionGroup>
  <Accordion title="View detailed comparison">
    | Feature                 | Managed by Portal          | Managed by YAML                |
    | ----------------------- | -------------------------- | ------------------------------ |
    | **Setup Speed**         | Immediate                  | Requires Pull Request approval |
    | **File Required**       | None                       | `catalog-info.yaml`            |
    | **Components per Repo** | One (1:1 mapping)          | One or more                    |
    | **Updates**             | Edit and bulk edit dialogs | Via Git commits or overlays    |
    | **Metadata Location**   | Portal database            | Repository files               |
    | **Version Control**     | No                         | Yes                            |
    | **Team Ownership**      | Centralized                | Distributed to teams           |
    | **Existing YAML**       | Ignored                    | Required or generated          |
  </Accordion>

  <Accordion title="Can I switch 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:** To change the management mode of already-ingested components, you need to unregister them and re-import them using the desired mode. For specific migration steps, refer to the [FAQ](./faq).
  </Accordion>
</AccordionGroup>

## What Fields Can I Manage?

Both modes allow you to specify core component fields:

* **Owner** - The team or user responsible for the component
* **Lifecycle** - Stage of the component (e.g., production, experimental, deprecated)
* **Type** - Component type (e.g., service, library, website)

In **Managed by YAML** mode, you have full control over the entire Portal entity format, including custom annotations, links, and relationships.

In **Managed by Portal** mode, you can edit entities later using the edit and bulk edit dialogs. During initial ingestion, you're limited to the core fields, but you can enhance components with additional metadata afterward. See [Updating Components](../catalog/bulk-editing) for details.

## Next Steps

Now that you understand the management modes, continue with the appropriate walkthrough:

* [Portal Mode Walkthrough](./portal-mode-walkthrough)
* [YAML Mode Walkthrough](./yaml-mode-walkthrough)