Skip to main content

Configure and manage action items

At the organization level, you decide what kinds of action items developers can work with and how they move through their lifecycle. This page covers both paths: driving it from the Platform Settings UI, or automating it with the np-governance agent plugin.

info

You need an Admin or Ops role to access this section.

Manage with the np-governance agent plugin​

The np-governance plugin lets you manage action items, categories, and AI suggestions through natural-language prompts from any compatible AI coding assistant (Claude Code, Factory AI, Codex CLI). It wraps the same API endpoints used throughout this page, but handles authentication, pagination, and deduplication for you.

For step-by-step examples of what you can do with the plugin, see the tutorials:

Managing categories​

Categories are the backbone of action items. They classify what each item tracks, how it appears in the UI, and what governance rules apply when developers triage it.

From Settings > Action Items > Categories, you see every category available in your organization, the NRN it applies to, and its status:

Categories list view in Platform Settings showing name, unit, status, and created date

Create a category​

Click New Category and fill in the form:

New category form in Platform Settings showing name, description, color, icon, unit, parent, and governance controls

Most fields are self-explanatory. A few to note:

FieldBehavior
Resource (NRN)Categories inherit down the NRN hierarchy, so a category defined at the organization level is available to every account and application below it.
Color / IconColor takes a hex code, icon takes an iconify name. Both determine how items in the category render in the UI.
Unit name / symbolDefines what "value" means on items in this category, for example "Dollars" / "$" or "Hours" / "h". The unit combines with priority to compute each item's score.
Parent categoryOptional. Supports up to two levels of nesting.

The same action is available via a POST request to /governance/action_item_category.

curl -L -X POST 'https://api.nullplatform.com/governance/action_item_category' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "nrn": "organization=1:account=2",
    "name": "Cost optimization",
    "description": "Tracks opportunities to reduce cloud spending",
    "color": "#38A169",
    "icon": "mdi:cash",
    "unit_name": "Dollars",
    "unit_symbol": "$",
    "config": {
        "requires_verification": false,
        "requires_approval_to_defer": true,
        "requires_approval_to_reject": false,
        "max_deferral_days": 60,
        "max_deferral_count": 2
    }
}'

Governance controls​

Each category carries a configuration block with the rules that control how developers can transition items in that category:

SettingEffect
Requires verification to resolveResolving an item moves it to pending_verification until an admin approves.
Requires approval to deferDeferring an item moves it to pending_deferral until an admin approves.
Requires approval to rejectRejecting an item moves it to pending_rejection until an admin approves.
Max deferral daysLimits how far into the future an item can be deferred.
Max deferral countLimits how many times an item can be deferred.
tip

Use these to enforce policy at the category level. For example, you can require verification on security vulnerabilities so they can't be silently marked resolved, while leaving cost optimization items fully in the hands of the developer.

Category inheritance​

Categories follow the NRN hierarchy. A category defined at organization=1 is available to every account, namespace, and application below it. If a more specific category with the same name exists at a lower level, the more specific one takes precedence.

This means you can set an organization-wide policy once, then override it for a specific account or application when needed.

Managing action items​

From Settings > Action Items > Items, you see every item across the organization, not just the ones attached to a single application.

Action items list in Platform Settings with filters for status, priority, category, and NRN

The list view supports the same filters as the developer list, plus NRN filtering so you can slice by account, namespace, or application.

Create an item manually​

Click New Action Item to create an item by hand. This is useful when you want to track improvements that aren't surfaced by an agent, such as manual audit findings or planned migrations.

New action item form in Platform Settings with fields for title, description, NRN, category, priority, value, due date, labels, affected resources, and references

The equivalent API call is a POST request to /governance/action_item.

curl -L -X POST 'https://api.nullplatform.com/governance/action_item' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "title": "Upgrade base image to fix CVE-2026-1234",
    "description": "The current base image has a critical vulnerability that allows remote code execution.",
    "category_slug": "security-vulnerabilities",
    "priority": "critical",
    "value": 500,
    "due_date": "2026-05-01T00:00:00Z",
    "labels": {
        "source": "container-scan",
        "cve": "CVE-2026-1234"
    }
}'

Approve or deny pending requests​

When a developer resolves, defers, or rejects an item whose category requires approval, the item lands in a pending_* state and surfaces here for admin review.

From the list view or detail page, you can:

  • Approve the request to let it transition to its final state.
  • Deny it to send the item back to open. A comment explaining the decision is required.

The underlying endpoints are POST approve and POST deny on /governance/action_item/{id}.

curl -L -X POST 'https://api.nullplatform.com/governance/action_item/xYz789AbCdEf/deny' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "comment": "The resolution evidence is insufficient. Please include test results."
}'

Close, reopen, or delete​

You have a few actions beyond approve and deny:

  • Close: close an item without resolution. Closed items are terminal. Use this for items that no longer apply, such as agent-generated items whose underlying issue has disappeared.
  • Reopen: bring a closed, rejected, or deferred item back to open.
  • Delete: permanently remove an item and its suggestions.

Admin workflow​

The core of the admin workflow is the pending_* review cycle. When a developer triggers an action in a category with an approval gate, the item lands in a pending state and waits for an admin decision:

Outside of this cycle, admins can also create items manually, close or reopen items, and delete them. Deferred items auto-reopen when their target date passes.

Admins do not resolve, defer, or reject items themselves. Those actions belong to developers. The admin role is to configure the rules and step in when a category requires approval.

Next steps​