Approval Workflow

Every write operation in AgentGate goes through a human-in-the-loop approval workflow. This page explains how it works, what the different statuses mean, and best practices for both agents and reviewers.

The Flow

Agent proposes change
        │
        ▼
   ┌─────────┐
   │ PENDING  │  ← Change created, nothing in Jira yet
   └────┬─────┘
        │
   Human reviews in Review UI or CLI
        │
   ┌────┴────┐
   │         │
   ▼         ▼
┌────────┐  ┌──────────┐
│APPROVED│  │ REJECTED │
└───┬────┘  └──────────┘
    │         Change discarded
    ▼         with reason
Applied to Jira
    │
    ├── Success → APPROVED (resultIssueKey set)
    │
    └── Failure → FAILED (retriable)

When an agent calls a write tool (like changes_create, comment, or issues_transition), it creates a pending change — a record of what the agent wants to do. Nothing in Jira is modified yet.

A human reviewer sees the pending change in the Review UI (built into Jira) or via the CLI, inspects the details, and approves or rejects.

If approved, the change is applied to Jira. If the apply fails (e.g., a permission issue), the change enters FAILED status and can be retried.

Change Statuses

Status	Meaning	What happens next
pending	Waiting for human review	Human approves or rejects, or agent cancels
approved	Applied to Jira successfully	resultIssueKey contains the created/updated issue key
rejected	Human rejected the change	rejectReason explains why — agent can adjust and re-propose
failed	Approved but apply failed	Can be retried. applyError describes what went wrong
cancelled	Agent or human cancelled	Change discarded, no action taken

The Review UI

The Review UI is accessible in Jira at Apps → AI Changes Review. It shows:

• All pending changes, grouped by type (create, update, transition, comment, delete)
• A diff view comparing proposed changes against the current Jira state
• The agent's reason for each change
• One-click Approve and Reject buttons
• Keyboard shortcuts for fast reviewing
• History of recently reviewed changes

Keyboard shortcuts

The Review UI supports keyboard shortcuts for fast reviewing when you have multiple pending changes. Hover over the buttons to see the shortcuts.

Hierarchical Changes

Some operations create parent-child change trees. For example, creating an Epic with child Stories produces one parent change (the Epic) and multiple child changes (the Stories).

Cascading rules:

• Approving a parent approves the entire tree
• Rejecting a parent cascades rejection to all children
• Cancelling a parent cascades cancellation to all children
• Individual children can be rejected without affecting siblings

This means a reviewer can approve an entire Epic + Stories structure with a single click, or reject the whole thing if the approach is wrong.

Execution is not transactional

Approval is unified but execution is not transactional. If a child issue fails during Jira creation (e.g., due to a permission issue), already-created siblings are not rolled back. Failed children can be retried individually.

Reviewing via CLI

For teams that prefer the terminal:

# List pending changes
jd changes list --status pending

# View details of a specific change
jd changes show chg-abc123

# Approve
jd changes approve chg-abc123

# Reject with reason
jd changes reject chg-abc123 --reason "Wrong priority, should be High"

Best Practices for Agents

1. Always provide a reason. Include a reason parameter when proposing changes. This helps reviewers understand intent without having to investigate.

2. Check before proposing. Call changes_list(status: "pending") before creating new changes to avoid duplicates.

3. Use hierarchical creates. When creating an Epic with Stories, use the children parameter to create the entire tree in one operation. This gives the reviewer a complete picture.

4. Handle rejections gracefully. If a change is rejected, read the rejectReason, adjust your approach, and re-propose.

5. Verify after approval. Use issues_show to confirm changes were applied correctly.

Best Practices for Reviewers

1. Review regularly. Pending changes block the agent from making progress. Quick reviews keep the workflow moving.

2. Use reject reasons. When rejecting, explain why. The agent uses this feedback to improve its next proposal.

3. Review trees as a whole. When you see a parent change with children, review the full tree before approving. Approving the parent approves everything.

4. Check the diff. The Review UI shows what will change compared to the current state. Use this to catch unintended modifications.