Returns entity or entities from the catalog by entity reference(s)
Input Schema
| Property | Type | Description | Required |
|---|---|---|---|
| optional | boolean | Allow the entity or entities to optionally exist. Default: false | |
| entityRef | string | Entity reference of the entity to get | |
| entityRefs | array | Entity references of the entities to get | |
| defaultKind | string | The default kind | |
| defaultNamespace | string | The default namespace |
Output Schema
| Property | Type | Description | Required |
|---|---|---|---|
| entity | any | Object containing same values used in the Entity schema. Only when used with `entityRef` parameter. | |
| entities | array | - |
Usage Examples
Fetch a component by name to reuse metadata
Retrieve an existing component using short name with default kind and namespace. Use its owner and tags to prefill values when generating a new service.
steps:
- id: getBaseComponent
action: catalog:fetch
input:
entityRef: ${{ parameters.baseComponentName }}
defaultKind: Component
defaultNamespace: default
- id: scaffoldFromTemplate
action: fetch:template
input:
url: ./skeleton
values:
serviceName: ${{ parameters.newServiceName }}
owner: ${{ steps.getBaseComponent.output.entity.spec.owner }}
tags: ${{ steps.getBaseComponent.output.entity.metadata.tags }}Fetch multiple groups to build CODEOWNERS
Look up several group entities by reference. Use the results to render a CODEOWNERS file for the repository.
steps:
- id: getOwnerGroups
action: catalog:fetch
input:
entityRefs:
- group:default/platform
- group:default/sre
- id: writeCodeowners
action: fs:write
input:
path: CODEOWNERS
contents: |
# Managed by Backstage
* @${{ steps.getOwnerGroups.output.entities[0].metadata.name }} @${{ steps.getOwnerGroups.output.entities[1].metadata.name }}Optionally fetch a system and skip if missing
Try to fetch a system entity that may not exist in all environments. Continue the workflow without failing and only add the system relation if it was found.
steps:
- id: getSystem
action: catalog:fetch
input:
entityRef: ${{ parameters.systemName }}
defaultKind: System
defaultNamespace: default
optional: true
- id: addSystemRelation
if: ${{ steps.getSystem.output.entity }}
action: fs:write
input:
path: catalog-info.yaml
contents: |
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: ${{ parameters.newServiceName }}
spec:
type: service
lifecycle: production
owner: ${{ parameters.owner }}
system: ${{ steps.getSystem.output.entity.metadata.name }}Resolve short refs for multiple components with defaults
Fetch dependencies using short names while providing default kind and namespace. Log the fully qualified refs to confirm what will be related.
steps:
- id: fetchDependencies
action: catalog:fetch
input:
entityRefs:
- ${{ parameters.dependencyA }}
- ${{ parameters.dependencyB }}
defaultKind: Component
defaultNamespace: default
- id: logDependencies
action: debug:log
input:
message: >
Will relate to components:
${{ steps.fetchDependencies.output.entities[0].kind }}:${{ steps.fetchDependencies.output.entities[0].metadata.namespace }}/${{ steps.fetchDependencies.output.entities[0].metadata.name }},
${{ steps.fetchDependencies.output.entities[1].kind }}:${{ steps.fetchDependencies.output.entities[1].metadata.namespace }}/${{ steps.fetchDependencies.output.entities[1].metadata.name }}Fetch user and group entities to set ownership
Retrieve a user and a fallback group to decide ownership metadata for the new component. Pass both to the template to choose at render time.
steps:
- id: getPrincipals
action: catalog:fetch
input:
entityRefs:
- user:default/jdoe
- group:default/platform
- id: renderScaffold
action: fetch:template
input:
url: ./skeleton
values:
owner: ${{ steps.getPrincipals.output.entities[0].metadata.name }}
fallbackOwner: ${{ steps.getPrincipals.output.entities[1].metadata.name }}