Understanding Management Modes
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.yamlfiles 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.yamlfiles 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
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 |
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.
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 for details.
Next Steps
Now that you understand the management modes, continue with the appropriate walkthrough: