Skip to main content
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

FeatureManaged by PortalManaged by YAML
Setup SpeedImmediateRequires Pull Request approval
File RequiredNonecatalog-info.yaml
Components per RepoOne (1:1 mapping)One or more
UpdatesEdit and bulk edit dialogsVia Git commits or overlays
Metadata LocationPortal databaseRepository files
Version ControlNoYes
Team OwnershipCentralizedDistributed to teams
Existing YAMLIgnoredRequired or generated
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: