> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Clean up stale entities

When you remove a resource type from your integration mapping or decommission an integration, the associated entities in Port are not automatically deleted. This documentation explains how to properly clean up stale entities to keep your software catalog accurate and up to date.

When cleanup is needed​

Cleanup is typically required when you:

  • Remove a kind from your integration mapping (for example, removing pull-request to stop syncing PRs).
  • Delete an integration entirely.
  • Rename a blueprint identifier.
  • Change your mapping in a way that orphans previously synced entities.

The 3-step cleanup process​

Removing stale entities requires completing these steps in order. Skipping a step or performing them out of sequence can leave orphaned data in your catalog.

Step 1: Remove the mapping​

Before deleting any entities, remove the resource mapping from your integration configuration. This prevents the integration from recreating the entities on the next resync.

  1. Go to your data sources page.

  2. Click on the integration you want to modify.

  3. Navigate to the Mapping tab.

  4. Remove the entire resource block for the kind you no longer want to sync.

  5. Click Save & Resync.

For example, if you no longer want to sync pull requests, remove this entire block:

- kind: pull-request
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: ".id | tostring"
        title: ".title"
        blueprint: '"pullRequest"'
        properties:
          # ... properties
Order matters

Always remove the mapping before deleting entities. If you delete entities first, the next integration resync will recreate them.

Step 2: Delete the entities​

Once the mapping is removed, delete the stale entities. You can do this through the UI or via the API.

Delete entities one by one

  1. Go to the catalog page for the relevant blueprint.

  2. On the entity you want to delete click on the ... button.

  3. Click on Unregister button in the toolbar.

  4. Confirm the deletion by clicking on Unregister again.

Delete all entities of a blueprint

If you need to delete all entities of a specific blueprint:

  1. Go to the catalog page for the blueprint.

  2. Click the ... menu in the top-right corner.

  3. Select Delete page.

  4. Click Delete to confirm the deletion.

Irreversible operation

Entity deletion is permanent and cannot be undone. Consider exporting your entities before deleting them if you might need the data later.

Step 3: Delete the blueprint (optional)​

If you no longer need the blueprint itself, delete it after all its entities have been removed.

  1. Go to the Builder page.

  2. Find the blueprint you want to delete.

  3. Click the ... menu on the blueprint card.

  4. Select Delete blueprint.

  5. Type DELETE and click on Delete to confirm the deletion.

Blueprint deletion requirements

You can only delete a blueprint if:

  • It has no remaining entities.
  • No other blueprints have required relations pointing to it.

If other blueprints reference this blueprint, update or remove those relations first.

When you delete a blueprint, Port also deletes any associated catalog pages that were automatically created for that blueprint.

Export before deletion​

Before deleting entities, you may want to export them for backup or audit purposes.

  1. Go to the catalog page for the blueprint.

  2. Click the Export button in the toolbar.

  3. Choose your export format (CSV or JSON) to download the file.

Handle dependent entities​

When deleting entities that are referenced by other entities through relations, you have two options:

Option 1: Auto-delete dependent entities​

Use the delete_dependents parameter to automatically delete entities that depend on the ones you're deleting:

curl -X DELETE "https://api.getport.io/v1/blueprints/<blueprint_identifier>/all-entities?delete_dependents=true" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN"

Option 2: Update relations first​

Manually update or remove the relations in dependent entities before deleting:

  1. Identify which entities reference the entities you want to delete.
  2. Update those entities to remove or change the relation values.
  3. Then delete the original entities.

Mapping configuration options​

Port provides configuration options to control automatic entity deletion during integration resyncs.

deleteDependentEntities​

When enabled, Port automatically deletes dependent entities when their parent entity is removed during a resync. Add this to your mapping configuration:

deleteDependentEntities: true
resources:
  - kind: repository
    # ...

entityDeletionThreshold​

Controls whether the integration's deletion mechanism is active. Set to 0 to disable automatic deletion or 1 to enable it:

entityDeletionThreshold: 1
resources:
  - kind: repository
    # ...

For more details on these options, see Configure mapping - Advanced options.

Troubleshooting​

Entities reappear after deletion​

If entities reappear after you delete them, the integration mapping still includes the resource type. Make sure you:

  1. Removed the kind from the mapping configuration.
  2. Saved and resynced the integration.
  3. Then deleted the entities.

Cannot delete blueprint​

If you cannot delete a blueprint, check for:

  • Remaining entities: Delete all entities of the blueprint first.
  • Incoming relations: Other blueprints may have relations pointing to this blueprint. Update or remove those relations first.

Dependent entities blocking deletion​

If you receive an error about dependent entities:

  • Use the delete_dependents=true parameter in your API call.
  • Or manually remove the relations from dependent entities first.