Update to Port Agent Skills (EU)

{
  "description": "Author and manage Port blueprints, entities, scorecards, and self-service actions with the official Terraform provider (port-labs/port-labs). Covers provider setup and auth, every resource type (port_blueprint, port_entity, port_scorecard, port_action, port_webhook, port_integration, port_aggregation_properties), the create/update/delete/import lifecycle, and known limitations that produce broken or silently wrong config. Use when asked to \"add a Port resource to Terraform\", \"manage Port as code\", \"write a port_blueprint/port_entity/port_action/port_scorecard resource\", \"import a Port blueprint into Terraform state\", or \"why did my Port terraform apply not do what I expected\".",
  "included_files": [
    {
      "relative_path": "assets/action.tf",
      "size_in_bytes": 3127
    },
    {
      "relative_path": "assets/blueprint.tf",
      "size_in_bytes": 2203
    },
    {
      "relative_path": "assets/entity.tf",
      "size_in_bytes": 2989
    },
    {
      "relative_path": "assets/scorecard.tf",
      "size_in_bytes": 2410
    },
    {
      "relative_path": "references/limitations.md",
      "size_in_bytes": 6252
    },
    {
      "relative_path": "references/resource-reference.md",
      "size_in_bytes": 21551
    }
  ],
  "name": "port-terraform",
  "skill_md_contents": "---\nname: port-terraform\ndescription: >-\n  Author and manage Port blueprints, entities, scorecards, and self-service\n  actions with the official Terraform provider (port-labs/port-labs).\n  Covers provider setup and auth, every resource type (port_blueprint,\n  port_entity, port_scorecard, port_action, port_webhook, port_integration,\n  port_aggregation_properties), the create/update/delete/import lifecycle,\n  and known limitations that produce broken or silently wrong config. Use\n  when asked to \"add a Port resource to Terraform\", \"manage Port as code\",\n  \"write a port_blueprint/port_entity/port_action/port_scorecard resource\",\n  \"import a Port blueprint into Terraform state\", or \"why did my Port\n  terraform apply not do what I expected\".\nlicense: MIT\ncompatibility: \"Claude Code, Cursor, Codex CLI, GitHub Copilot\"\nmetadata:\n  version: \"1.0.0\"\n  author: port-labs\n  repository: https://github.com/port-labs/port-skills\n  tags: port,terraform,iac,reference\n  summary: Manage Port resources as code with the Terraform provider\n---\n\n# Port Terraform provider\n\nPort's Terraform provider (`port-labs/port-labs`) lets you define blueprints,\nentities, scorecards, self-service actions, webhooks, and integration\nmappings as `.tf` resources, the same way you'd define any other piece of\ninfrastructure. This skill is reference-only: static knowledge about the\nprovider's resource schema, drawn from the current v2.x provider and Port's\nTerraform docs. It doesn't need a live Port account or Port MCP server to\nproduce correct HCL, only a real account and API credentials to actually\n`terraform apply` it.\n\nOut of scope: the underlying Port concepts (property types, relation\nsemantics) are owned by the `port-blueprints` skill; self-service action\nJSON schema and invocation method payload templating aren't covered by a\nskill in this repo yet. This skill only covers how those concepts map onto\nTerraform arguments. Pulumi is Port's\nother IaC provider, briefly noted in [Step 1](#step-1---set-up-the-provider),\nbut not covered in depth here.\n\n## Prerequisites\n\n- Go over the `port-getting-started` skill first if this is your first time working with Port.\n- The [Terraform CLI](https://learn.hashicorp.com/tutorials/terraform/install-cli) (or [OpenTofu](https://opentofu.org/docs/intro/install/), a drop-in alternative, swap `terraform` for `tofu`).\n- A Port account and a `client_id`/`client_secret` pair, from **...** menu > **Credentials** in the Port app, or the [API docs](https://docs.port.io/build-your-software-catalog/custom-integration/api#find-your-port-credentials).\n- No Port MCP server or CLI is required to write or apply the `.tf` files this skill produces. If one is connected, use it to check the current live state (`list_blueprints`) before writing HCL that should match it, and search `search_port_knowledge_sources` for anything this skill doesn't cover.\n\n## Step 1 - Set up the provider\n\nPrecondition: no `port` provider block exists in the working directory yet.\nAction: add a `terraform` block pinning `port-labs/port-labs`, and a\n`provider \"port\"` block with credentials from environment variables, then\nrun `terraform init`:\n\n```hcl\nterraform {\n  required_providers {\n    port = {\n      source  = \"port-labs/port-labs\"\n      version = \"~> 2.4.0\"\n    }\n  }\n}\n\nprovider \"port\" {\n  client_id = \"\" # or set the environment variable PORT_CLIENT_ID\n  secret    = \"\" # or set the environment variable PORT_CLIENT_SECRET\n  base_url  = \"https://api.port.io\"\n}\n ```\n\n```bash\nterraform init\n ```\n\nFallback: if the user's stack is Python, TypeScript, JavaScript, or Go\ninstead of HCL, Port also ships a Pulumi provider with the same `Entity`\nresource concept. Point them at\n[docs.port.io's Pulumi page](https://docs.port.io/build-your-software-catalog/custom-integration/iac/pulumi/)\ninstead of forcing Terraform.\n\n## Step 2 - Model data with `port_blueprint`\n\nPrecondition: the context lake needs a new type, or an existing blueprint needs\nto move under Terraform management.\nAction: write a `port_blueprint` resource with `identifier`, `title`, typed\n`properties`, and any `relations` to other blueprints. See\n[references/resource-reference.md](references/resource-reference.md) for\nthe full property-type and relation argument tables, and\n[assets/blueprint.tf](assets/blueprint.tf) for a complete example.\nFallback: if a relation's `target` blueprint doesn't exist yet, define it\nfirst, `port_blueprint.relations` requires an existing target and Terraform\nwon't infer creation order across two relations pointing at each other\nwithout an explicit `depends_on`.\n\n## Step 3 - Populate the context lake with `port_entity`\n\nPrecondition: a blueprint exists (via Terraform or otherwise) and you need\nto create, update, or manage a specific instance of it.\nAction: write a `port_entity` resource with `blueprint`, `title`, an\nexplicit `identifier`, and `properties`/`relations` matching the blueprint's\nschema. See [assets/entity.tf](assets/entity.tf) for single and many\nrelations together.\nFallback: if you're bringing an entity that already exists in Port under\nTerraform management, don't start from a partial definition, see\n[Limitations #3](references/limitations.md) first: unspecified properties\nget overridden with empty values, not left alone.\n\n## Step 4 - Add scorecards with `port_scorecard`\n\nPrecondition: entities of a blueprint need a maturity or readiness score.\nAction: write a `port_scorecard` resource with `blueprint`, `rules`\n(`identifier`, `title`, `level`, `query`), and optionally custom `levels`.\nEach rule's `query.conditions` is a list of `jsonencode()`'d condition\nobjects, not native HCL. See\n[assets/scorecard.tf](assets/scorecard.tf).\nFallback: if a rule's `level` doesn't match one of the scorecard's `levels`\n(or the defaults `Basic`/`Bronze`/`Silver`/`Gold` when `levels` is omitted),\n`terraform apply` rejects the rule, define the levels first.\n\n## Step 5 - Add self-service actions and automations with `port_action`\n\nPrecondition: users need a form to trigger a backend (self-service action),\nor an event in Port needs to trigger one automatically (automation).\nAction: write a `port_action` resource with exactly one of\n`self_service_trigger` / `automation_trigger`, and exactly one invocation\nmethod block (`webhook_method`, `github_method`, `gitlab_method`,\n`azure_method`, `kafka_method`, `upsert_entity_method`, or\n`integration_method`). See\n[references/resource-reference.md](references/resource-reference.md) for\nthe full trigger and invocation-method argument tables, and\n[assets/action.tf](assets/action.tf) for a self-service action plus an\nautomation in one file.\nFallback: if a `user_properties` entity-picker `dataset` mixes a static rule\nwith a `jq_query` rule, don't use the native HCL `dataset` block, wrap the\nwhole thing in `jsonencode()`, see\n[Limitations #1](references/limitations.md).\n\n## Step 6 - Sync webhooks, integrations, and aggregations\n\nPrecondition: you need a custom inbound webhook (`port_webhook`), to bring\nan already-installed Ocean integration's mapping under version control\n(`port_integration`), or to add computed count/average properties across\nrelated entities (`port_aggregation_properties`).\nAction: see the per-resource argument tables in\n[references/resource-reference.md](references/resource-reference.md).\n`port_integration` manages an *existing* installation only, always\n`terraform import` it first (Step 7).\nFallback: a `port_aggregation_properties` property returns `null` or `0`\nwith no error when more than one relation path connects the two blueprints\nand `path_filter` isn't set, see\n[Limitations #2](references/limitations.md).\n\n## Step 7 - Import existing Port resources into Terraform state\n\nPrecondition: a blueprint, entity, scorecard, action, webhook, integration,\nor aggregation property already exists in Port and needs to come under\nTerraform management.\nAction: add a resource block (even an empty one to start), then run\n`terraform import <resource_type>.<name> \"<id>\"` with the ID format from the\n[import table](references/resource-reference.md#lifecycle-create-update-delete-import),\nthen `terraform plan` to check for drift before the next `apply`.\nFallback: if the resource block doesn't match the imported state,\n`terraform plan` shows the mismatch as drift to fix, and applying it will\noverwrite (or empty out) the real Port resource, don't apply until the plan\nshows no unexpected changes.\n\n## Examples\n\nComplete, standalone `.tf` files (each includes its own `terraform` and\n`provider` block):\n\n- [assets/blueprint.tf](assets/blueprint.tf): two related blueprints, all five property-group types.\n- [assets/entity.tf](assets/entity.tf): entities wired up with a single relation and a many relation.\n- [assets/action.tf](assets/action.tf): a self-service create action with a webhook backend, plus an automation.\n- [assets/scorecard.tf](assets/scorecard.tf): custom levels and multiple JQ-based rules.\n\n## Common pitfalls\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `port_action` config rejected, or built from a stale example | Top-level `user_properties`/`operation` on `port_action` is the deprecated v1.x shape | Nest under `self_service_trigger` or `automation_trigger`, see [Limitations #6](references/limitations.md) |\n| Entity-picker dataset doesn't filter correctly | Mixed static and `jq_query` rules in a native HCL `dataset` block | `jsonencode()` the whole `dataset` object, see [Limitations #1](references/limitations.md) |\n| Aggregation property is `null`/`0` with no error | Ambiguous relation path between blueprints | Add `path_filter`, see [Limitations #2](references/limitations.md) |\n| Updating an existing entity wipes properties you didn't touch | `port_entity` uses create/override, not merge | Reproduce the entity's full current state in the resource body |\n| `terraform destroy` fails on a blueprint | Entities exist that weren't created by this Terraform state | Set `force_delete_entities = true` before destroying |\n| Changing a property's `type` is blocked | `blueprint_property_type_change_protection` defaults to `true` | Add a new property with the right type, migrate data, remove the old one, don't disable the protection |\n| Drift wipes a resource right after `terraform import` | Resource block doesn't match the real imported state | Reconcile the block with `terraform plan` before the first `apply` |\n\n## Quick reference\n\n- Provider: `provider \"port\" { client_id, secret, base_url }`, or\n  `PORT_CLIENT_ID`/`PORT_CLIENT_SECRET` env vars.\n- Resources: `port_blueprint`, `port_entity`, `port_scorecard`,\n  `port_action`, `port_webhook`, `port_integration`,\n  `port_aggregation_properties`.\n- Property groups (blueprint and entity): `string_props`, `number_props`,\n  `boolean_props`, `object_props`, `array_props`.\n- Relation groups (entity only): `single_relations`, `many_relations`.\n- Action triggers: `self_service_trigger` (`CREATE`/`DAY-2`/`DELETE`) or\n  `automation_trigger` (event-based). Exactly one per action.\n- Action invocation methods: `webhook_method`, `github_method`,\n  `gitlab_method`, `azure_method`, `kafka_method`, `upsert_entity_method`,\n  `integration_method`. Exactly one per action.\n- Import ID formats: full table in\n  [references/resource-reference.md](references/resource-reference.md#lifecycle-create-update-delete-import).\n- Full argument reference:\n  [references/resource-reference.md](references/resource-reference.md).\n  Known gotchas: [references/limitations.md](references/limitations.md).\n"
}