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

# YAML Mode Walkthrough

> Step-by-step guide to ingesting repositories using YAML-managed mode — register existing catalog-info.yaml files or create them via pull requests.

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.

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/30KNAI5WzZFwyWnx/portal/core-features-and-plugins/catalog-builder/assets/catalog-builder-azure-metadata-missing.png?fit=max&auto=format&n=30KNAI5WzZFwyWnx&q=85&s=3d0f7441e358144cf544ac3aa99ffdfc"
    alt="Catalog Builder Missing
Steps"
    width="3824"
    height="1846"
    data-path="portal/core-features-and-plugins/catalog-builder/assets/catalog-builder-azure-metadata-missing.png"
  />
</Frame>

> 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`:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
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](./troubleshooting) for common problems and solutions, including:

* Pull Requests not being created
* Components not appearing after merge
* Invalid YAML errors