Manage scorecard groups

Feature availability

Scorecard groups are protected by the SCORECARD_GROUPS organization feature flag and are not available in all Port organizations. If you need access, contact your Port account team.

A scorecard group lets you manage scorecards across multiple blueprints as a single unit. When you create a group, Port creates one related scorecard per blueprint and links them together.

Why use scorecard groups

Some standards apply to more than one entity type. "Production readiness" may be a question you ask about services, repositories, and infrastructure resources alike. "Ownership hygiene" may be something you want to track across most of your catalog.

Without groups, each blueprint needs its own scorecard. In practice that means:

• The same rule is written and maintained several times, and the copies drift apart as standards evolve.
• There is no single answer to "how are we doing on production readiness", only a score per blueprint.
• Rolling out a change to a standard is a manual, repetitive task across every scorecard.

Scorecard groups let you define a standard once and apply it everywhere it belongs:

• Define once, apply everywhere. Write the rules and levels a single time. Port creates and maintains a related scorecard for each blueprint in the group.
• Keep scores comparable. Levels stay consistent across all members, so Gold means the same thing whether you are looking at a service or a repository.
• Adapt without forking the standard. Use per-blueprint filters to scope which entities are evaluated, or per-blueprint rules when the check itself differs by entity type.
• Report on the standard as one unit. A group aggregates results across its members, giving platform and leadership a single view of adoption instead of a score per blueprint.
• Manage standards as code. The Terraform resource lets standards go through the same review and rollout process as the rest of your infrastructure.

You can also bring existing scorecards into a group rather than rebuilding them, as long as their levels match the group's levels.

Common use cases

Scenario	How a group helps
Production readiness across services, repositories, and infrastructure	One set of rules and levels, with filters that limit each blueprint to production entities.
Security or compliance baselines (for example SOC 2 controls)	A single standard evaluated across every entity type in scope, with one aggregated compliance view.
Ownership and metadata hygiene	The same "has an owner", "has a Slack channel" checks applied catalog-wide.
Maturity models where checks differ by entity type	Per-blueprint rules under one group title and one shared set of levels.

If a standard applies to a single blueprint, a standalone scorecard is still the simpler choice.

Enable scorecard groups

Before you create or change scorecard groups, enable them for your organization. This operation is idempotent and can only be performed by an admin.

Make a POST request to https://api.port.io/v1/scorecards/enable-groups.

Enable scorecard groups example (click to expand)

curl -X POST 'https://api.port.io/v1/scorecards/enable-groups' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Configuration modes

A scorecard group can be configured in one of two modes. The blueprints/rules/filters fields and the scorecards map are mutually exclusive - provide exactly one shape in each request.

Shared rules mode

Set blueprints, rules, and optionally filters to apply the same rules to multiple blueprints. Use filters when you need different entity filters per blueprint while keeping the same rules.

Per-blueprint mode

Set scorecards to define different rules and filters for each blueprint. Use this when blueprints need distinct rule sets under the same group title and levels.

Related scorecard identifiers

When Port creates related scorecards for a group, each scorecard identifier follows this pattern:

{blueprint_identifier}_{group_identifier}

For example, a group with identifier production-readiness on the microservice and team blueprints creates scorecards with identifiers microservice_production-readiness and team_production-readiness.

Manage scorecard groups

Port offers the following ways to create, edit, and delete scorecard groups:

API

Access token required

Remember that an access token is necessary in order to make API requests. If you need to generate a new token, refer to getting an API token.

Create scorecard groups

Make a POST request to https://api.port.io/v1/scorecard-groups. See the create a scorecard group API reference.

Shared rules mode example (click to expand)

{
  "identifier": "production-readiness",
  "title": "Production Readiness",
  "blueprints": ["microservice", "team"],
  "levels": [
    { "color": "paleBlue", "title": "Basic" },
    { "color": "bronze", "title": "Bronze" },
    { "color": "silver", "title": "Silver" },
    { "color": "gold", "title": "Gold" }
  ],
  "rules": [
    {
      "identifier": "has-owner",
      "title": "Has Owner",
      "level": "Gold",
      "query": {
        "combinator": "and",
        "conditions": [
          {
            "property": "$team",
            "operator": "isNotEmpty"
          }
        ]
      }
    }
  ],
  "filters": {
    "microservice": {
      "combinator": "and",
      "conditions": [
        {
          "property": "lifecycle",
          "operator": "=",
          "value": "production"
        }
      ]
    },
    "team": {
      "combinator": "and",
      "conditions": [
        {
          "property": "status",
          "operator": "=",
          "value": "active"
        }
      ]
    }
  }
}

Per-blueprint mode example (click to expand)

{
  "identifier": "readiness",
  "title": "Readiness",
  "levels": [
    { "color": "paleBlue", "title": "Basic" },
    { "color": "bronze", "title": "Bronze" },
    { "color": "silver", "title": "Silver" },
    { "color": "gold", "title": "Gold" }
  ],
  "scorecards": {
    "microservice": {
      "rules": [
        {
          "identifier": "has-owner",
          "title": "Has Owner",
          "level": "Gold",
          "query": {
            "combinator": "and",
            "conditions": [
              {
                "property": "$team",
                "operator": "isNotEmpty"
              }
            ]
          }
        }
      ]
    },
    "team": {
      "rules": [
        {
          "identifier": "has-slack",
          "title": "Has Slack Channel",
          "level": "Silver",
          "query": {
            "combinator": "and",
            "conditions": [
              {
                "property": "slackChannel",
                "operator": "isNotEmpty"
              }
            ]
          }
        }
      ]
    }
  }
}

---

Get scorecard groups

• To list all scorecard groups, make a GET request to https://api.port.io/v1/scorecard-groups. See the get all scorecard groups API reference.
• To get a single scorecard group, make a GET request to https://api.port.io/v1/scorecard-groups/{scorecard_group_identifier}. See the get a scorecard group API reference.

When all related scorecards share identical rules, the response uses the shared-rules shape (blueprints, rules, and optional filters). When member rules differ, the response uses the per-blueprint shape (scorecards map).

---

Update scorecard groups

Make a PUT request to https://api.port.io/v1/scorecard-groups/{scorecard_group_identifier}. See the change a scorecard group API reference.

The request body must include the full desired group definition. Port creates, updates, or deletes related scorecards as needed. The body identifier must match the path identifier.

Shrinking a group to a single blueprint keeps the group. To remove a group entirely, use the delete endpoint.

---

Delete scorecard groups

Irreversible delete

Deleting a scorecard group also deletes all of its related scorecards, including their rules and results. This action cannot be undone.

Make a DELETE request to https://api.port.io/v1/scorecard-groups/{scorecard_group_identifier}. See the delete a scorecard group API reference.

---

Add an existing scorecard to a group

Make a POST request to https://api.port.io/v1/scorecard-groups/{scorecard_group_identifier}/scorecards/{scorecard_identifier}. See the add a scorecard to a group API reference.

Port validates that the scorecard's levels match the group. If the scorecard is already in another group, the request is rejected unless you pass overrideGroup=true, which moves the scorecard and deletes the previous group if it becomes empty.

A group can have at most one related scorecard per blueprint.

---

Remove a scorecard from a group

Make a DELETE request to https://api.port.io/v1/scorecard-groups/{scorecard_group_identifier}/scorecards/{scorecard_identifier}. See the remove a scorecard from a group API reference.

If the removed scorecard was the last member, Port deletes the group entity and the scorecard remains as a standalone scorecard.

Terraform

Use the port_scorecard_group resource from the Terraform provider to manage scorecard groups.

Create scorecard groups

Shared rules mode example (click to expand)

resource "port_scorecard_group" "readiness" {
  identifier = "production-readiness"
  title      = "Production Readiness"
  blueprints = [
    port_blueprint.microservice.identifier,
    port_blueprint.team.identifier,
  ]

  rules = [{
    identifier = "has-owner"
    title      = "Has Owner"
    level      = "Gold"
    query = {
      combinator = "and"
      conditions = [jsonencode({
        property = "$team"
        operator = "isNotEmpty"
      })]
    }
  }]
}

Per-blueprint mode example (click to expand)

resource "port_scorecard_group" "readiness" {
  identifier = "production-readiness"
  title      = "Production Readiness"

  scorecards = {
    (port_blueprint.microservice.identifier) = {
      rules = [{
        identifier = "has-owner"
        title      = "Has Owner"
        level      = "Gold"
        query = {
          combinator = "and"
          conditions = [jsonencode({
            property = "$team"
            operator = "isNotEmpty"
          })]
        }
      }]
    }
    (port_blueprint.team.identifier) = {
      rules = [{
        identifier = "has-slack"
        title      = "Has Slack Channel"
        level      = "Silver"
        query = {
          combinator = "and"
          conditions = [jsonencode({
            property = "slackChannel"
            operator = "isNotEmpty"
          })]
        }
      }]
    }
  }
}

---

Update scorecard groups

Update the port_scorecard_group resource definition and run terraform apply.

---

Delete scorecard groups

Irreversible delete

Deleting a scorecard group also deletes all of its related scorecards. This action cannot be undone.

Run terraform destroy -target=port_scorecard_group.<resource_id>, or remove the resource from your .tf file and run terraform apply.

Q&A

API reference

Scorecard groups are managed by the following endpoints:

• Create a scorecard group and related scorecards
• Get all scorecard groups and related scorecards
• Get a scorecard group and related scorecards
• Change a scorecard group and related scorecards
• Delete a scorecard group and related scorecards
• Add a scorecard to a group
• Remove a scorecard from a group

Next steps

• Learn how to manage individual scorecards in Port.
• Explore scorecard use cases you can implement in your environment.