Updating Components

After ingesting components into your catalog, you’ll need to keep their metadata up to date. Portal provides two editing interfaces for updating component information.

​

Editing Portal-Managed Components

For components managed by Portal, use these editing tools to update metadata:

​

Edit Entity Dialog

Update individual components using the Edit Entity dialog, which provides a focused interface for modifying a single component’s metadata. To access:

• Navigate to the component’s page in the catalog
• Click the 3 vertical dots in the top right
• Click the edit entity button

​

Bulk Edit Dialog

Update multiple components at once using the Bulk Edit dialog. This is the most efficient way to apply consistent changes across many components. To access:

• Select multiple components from the catalog page
• Click the pencil icon next to the filters in the top right.

These are the primary ways to manage Portal-managed entities. All metadata changes are immediately saved to Portal’s database.

​

Editing YAML-Managed Components

For components managed by YAML, you have three ways to update metadata:

​

1. Edit the catalog-info.yaml File

Update components by directly editing the catalog-info.yaml file in your repository. Portal automatically syncs changes when you commit to your repository. This is the source of truth for YAML-managed components.

​

2. Edit Entity Overlay

Update individual components using the Edit Entity Overlay dialog. This provides the same UI interface as Portal-managed components but applies changes as overlays on top of the YAML definition. To access:

• Navigate to the component’s page in the catalog
• Click the 3 vertical dots in the top right
• Click the edit entity button

​

3. Bulk Edit Dialog

Update multiple YAML-managed components at once using the Bulk Edit dialog. These changes are also applied as overlays on top of the YAML definitions. To access:

• Select components from the catalog page
• Click the pencil icon next to the filters in the top right

You can also access it directly from an Entity’s page via the “Edit Entity” button.

---

Both editing interfaces support updating core component fields including owner, lifecycle, type, labels, and annotations.

​

Changing Entity Kind

You can change an entity’s kind — for example, converting a Component to an API, or a System to a Domain. This is only supported for entities managed by Portal.

​

How It Works

When you change an entity’s kind:

1. A new entity is created with the selected kind and the same name
2. The original entity is marked as deleted
3. You’re redirected to the new entity’s page in the catalog

Since the entity kind is part of its unique reference (e.g., component:default/my-service vs api:default/my-service), a kind change creates a new identity for the entity rather than modifying the existing one.

​

Spec Field Handling

Each entity kind supports a different set of spec fields. When you change an entity’s kind, Portal automatically:

• Keeps spec fields that are valid for both the old and new kind
• Removes spec fields that don’t apply to the new kind

Before confirming the change, the dialog shows which fields will be removed so you can review the impact.

​

Supported Kinds

Kind changes are supported between Component, API, System, and Domain. The new kind’s entity ref must not already exist in the catalog.