Agent Ledger for Jira

Documentation

Version 1.0 · Effective November 11, 2026

Agent Ledger estimates which Jira work items AI coding agents such as GitHub Copilot, Claude Code, Cursor, OpenAI Codex, and Devin handled, and compares that work with your team's: cycle time, revert rate, rework rate, and cost per item. Attribution is an estimate, with a confidence level per work item. This guide covers install, where to find each feature, configuration, and a step-by-step way to test every feature with sample data.

The App stores metadata only. It does not store work-item descriptions, comment text, attachments, or source code. It runs on Atlassian Forge and keeps its data in Forge storage in your site's data residency location. It does not call servers outside Atlassian.

1. Install

A Jira admin installs the App from the Atlassian Marketplace and approves its permissions. The permissions and why the App asks for each one are listed on the security practices page.

After install:

  1. Open Agent Ledger settings (see section 2) and, if you do not want every project included, enter the project keys to track.
  2. Click Save.
  3. Wait for the first nightly sync. The settings page says "First sync runs tonight." until that run has finished. The first sync backfills work items updated in the last 90 days. If the site is large, backfill can take more than one nightly run; the settings page will say "backfill in progress" until it is complete.

There is no "run sync now" control. The Agent Ledger page and the dashboard gadget stay empty until a sync has built a monthly summary. Cost figures appear after you upload a cost CSV (section 4), once that month already has stored work items.

2. Where to find each feature

Feature Manifest module Where it appears in Jira
Agent Ledger page jira:globalPage agent-ledger-global, title Agent Ledger Jira navigation: Apps → Agent Ledger
Dashboard gadget jira:dashboardGadget agent-ledger-gadget, title Agent Ledger Any Jira dashboard: Add gadget, search for Agent Ledger. It needs no setup and shows the current month.
Work item panel jira:issuePanel agent-ledger-panel, title Agent Ledger Open a work item, open the Apps menu on that work item, and add Agent Ledger. The panel stays on work items once it has been added.
Settings jira:adminPage agent-ledger-admin, title Agent Ledger settings Jira settings (the gear) → Apps → Agent Ledger settings. Jira admins only.

If the site's license is not active, the Agent Ledger page and gadget ask you to have a Jira admin activate the App, and the work item panel says "Agent Ledger license inactive." The nightly sync does not run on an unlicensed site.

3. The Agent Ledger page

Open Apps → Agent Ledger. Choose a Month from the last six calendar months (months are in UTC). When a summary exists for that month, the page shows:

  • Agent share of done work — how many done work items the App estimated as agent-handled, out of all done items in the tracked projects.
  • Median cycle time (agent / human) — time from the first move into an In Progress status to the last move into Done. If a work item skipped In Progress, this is created-to-Done. Work items you create and complete in a few minutes will show a very short cycle time.
  • Revert rate (agent / human) and Rework rate (agent / human).
  • Agent cost per item — shown after a Jira admin uploads monthly spend in settings. Until then, the hint says "upload costs in settings".
  • By agent — for each detected tool: done count, median cycle time, pull-request merge rate, revert rate, rework rate, and cost per item.
  • Agent-handled items — the work item key (links to the work item), tool, confidence, cycle time, and outcome. Up to 20 rows per page.

A footer notes when the summary was built. If no month has data yet, the page says "No data yet" and tells you the first sync runs nightly after install.

Outcomes

Each agent-handled work item gets one outcome. Revert wins over rework, and rework wins over a clean merge:

Outcome Meaning
reverted A linked pull request was merged, then reverted within 30 days (a later commit message such as This reverts commit <sha> or Revert "<title>").
reworked After the first merge, another linked pull request or commit for the same work item landed within 14 days, and it was not a revert.
merged At least one linked pull request merged, with no revert or rework in those windows.
no merge Linked pull requests exist, but none merged.
no PR No linked pull requests.

The dashboard gadget

The gadget shows the same KPI row as the Agent Ledger page for the current month (or a saved month, if a gadget configuration ever includes one). It has no settings screen. If there is no summary yet, it says "No Agent Ledger data yet."

The work item panel

On a work item the panel shows whether the App estimated the work as agent-handled or human, the tool name, confidence and score when it is agent work, the signals it found, the outcome, and any linked pull requests (state, title, and a reverted marker when one applies).

Linked pull requests are read through Atlassian's Teamwork Graph as the person viewing the page, so you only see pull requests you already have access to. If Teamwork Graph is unavailable, the panel says so and shows any cached pull requests.

The panel uses stored work-item facts for Jira labels, assignees, and status changes. Those facts are written by the nightly sync. Until the first sync has run, a panel on a work item that only has Jira labels (and no linked pull requests) may not yet show those label signals.

4. Configuration

Open Agent Ledger settings. The page title is already "Agent Ledger settings"; the App does not repeat a heading.

Last sync. After a sync has run, a line such as "Last sync \<time>: N changed, backfill complete." appears at the top. Before the first run it says "First sync runs tonight."

Projects to track (comma-separated keys; empty = all). Enter keys such as DEMO, ABC. The App stores them in uppercase. A key must start with a letter and then use only letters, digits, or underscores. Leave the field empty to include every project. Click Save. You should see "Saved: DEMO, ABC" (or "Saved: all projects"). Changing projects or the threshold takes effect on the next nightly sync; this screen does not rebuild months by itself.

Attribution threshold (default 3; higher = stricter). A work item is estimated as agent-handled when its best tool score is at least this number. Allowed values are 1 to 10. See section 5 for how scores are built.

Agent costs (CSV). Format: tool,month,amount_usd, for example cursor,2026-10,400. A header line tool,month,amount_usd is allowed, and lines that start with # are ignored. Tool names are stored in lowercase. Click Upload costs. A successful upload says "Saved N cost rows" and immediately rebuilds the summaries for the months in the file, so cost per item can appear without waiting for the next sync. If a line is invalid, nothing is saved and the page says "Fix lines: …".

Optional: GitHub webhook. Use this when you want pull request authors, branch names, commit trailers, and reverts for repositories that are not already connected to Jira. If your repositories are already connected through Jira's development integration, the App can read linked pull requests without the webhook.

  1. Click Show webhook URL and copy the URL. It is unique to your site; treat it like a password.
  2. Under the secret field, enter a random secret of 20 or more characters and click Save secret. The page says "Webhook secret saved." The secret is never shown again. The field then shows "secret is set (enter to replace)". A shorter secret is rejected with "secret must be >= 20 chars".
  3. In GitHub, open the repository's Settings → Webhooks → Add webhook. Paste the URL, set the content type to application/json, paste the same secret, and enable the Pull requests, Pull request reviews, and Pushes events.

The App checks each delivery's signature and rejects a bad signature (GitHub then shows status 401). Nothing is sent back to GitHub. Webhook data is included in the reports after the next nightly sync. If you later uninstall the App, delete the webhook in GitHub too.

5. How attribution works

Attribution is an estimate. The App looks only at metadata: Jira app users, labels, pull request authors, branch names, commit trailers, and short marker phrases in a pull request body. It does not read work-item descriptions or source code to decide.

A work item is estimated as agent-handled when the score for its best-matching tool is at least the attribution threshold (3 by default). Each kind of signal counts once per tool:

Signal Weight How to produce it in a test
Assigned to, or transitioned by, a known agent app user 3 An app account whose display name matches a known tool (for example "GitHub Copilot")
Jira label ai-agent, agent-authored, or ai-generated 3 Add the label. Use ai-agent:cursor (or :copilot, :claude, :codex, :devin) to name the tool
Linked pull request opened by a known agent bot 3 A linked PR whose author login is a known bot, such as copilot or cursor[bot]
Matching label on the pull request 3 The same label names as above, on the PR
Commit trailer such as Co-authored-by: copilot 3 On a linked commit (the optional GitHub webhook is the usual source for trailers)
Branch prefix copilot/, codex/, claude/, cursor/, or devin/ 2 A linked PR from that branch
Marker phrase in the pull request body, such as "Generated with Claude Code" 1 A linked PR whose description contains a known marker
Comment on the work item by a known agent app user 1 A comment from that app account

Confidence when the score meets the threshold:

  • high — score is at least twice the threshold (independent signals agree)
  • medium — score is at least 1.5 times the threshold
  • low — score is at or just above the threshold (for example a single ai-agent label at the default threshold of 3)

The tools the App recognizes are GitHub Copilot, OpenAI Codex, Claude Code, Cursor, and Devin.

6. Test every feature with sample data

Use a project you can edit, with a short key such as DEMO. Do not use real customer data, real spend, or real secrets. Months on the Agent Ledger page are UTC, so create and complete the sample work items in the UTC month you plan to open.

A. Settings

  1. Install the App and keep the license active.
  2. Open Jira settings → Apps → Agent Ledger settings.
  3. Set Projects to track to DEMO and leave the threshold at 3. Click Save. Confirm the success message lists DEMO.
  4. Confirm the sync line is either "First sync runs tonight." or a last-sync line with a changed count and a backfill status.

B. Sample work items

In project DEMO, create work items in the current UTC month and move them to Done so they appear in that month's summary. A simple set:

  1. Human work. Two or more work items with no agent labels and no agent pull requests. Complete them.
  2. Agent work, low confidence. Two or more work items labeled ai-agent:copilot (or ai-agent:cursor). Complete them. At the default threshold of 3, a single such label is enough, with low confidence.
  3. Agent work, higher confidence (optional). A work item with both an ai-agent:claude label and a linked pull request from a claude/ branch, or a pull request body that contains "Generated with Claude Code". That should raise the score and the confidence.
  4. Open work (optional). One labeled work item left In Progress. It should not count in "done work" on the month summary.

If Jira already lists development information on a work item, open that item after the sync and confirm the panel shows the linked pull request state.

C. Wait for the nightly sync

Wait until the settings page shows a last-sync time. For the first install, that is the first daily run after install, and backfill may still be "in progress" if not all pages have been read yet. You cannot trigger the sync from the UI.

After a last-sync line appears, continue.

D. Agent Ledger page

  1. Open Apps → Agent Ledger.
  2. Select the UTC month in which you completed the sample work items.
  3. Confirm Agent share of done work counts the labeled items against all done sample items (for example, 2 of 4 if you completed two agent items and two human items).
  4. Confirm By agent has a row for copilot (or whichever tool you labeled).
  5. Confirm Agent-handled items lists the labeled keys, the tool, confidence low (for a single label), a cycle time, and outcome no PR if you did not link pull requests.
  6. Click a key and confirm it opens that work item.

If the page still says "No data yet," the sync has not written a summary for that month. Check the settings sync line and that the work items are in a tracked project, were updated in the backfill window, and are Done in the month you selected.

E. Work item panel

  1. Open one labeled, completed work item.
  2. From the work item Apps menu, add Agent Ledger if it is not already on the item.
  3. Confirm the panel shows an Agent lozenge with the tool, confidence low (score 3) for a single label, a Signals line that includes the Jira label, and outcome no PR (or the pull-request outcome, if you linked one).
  4. Open a human sample work item and confirm the panel shows Human.

F. Dashboard gadget

  1. Open a Jira dashboard you can edit (or create a test dashboard).
  2. Add gadget, search for Agent Ledger, and add it. Do not look for a configuration screen; there isn't one.
  3. Confirm the gadget shows the same KPI values as the Agent Ledger page for the current UTC month. If you are testing an older month on the page, the gadget still shows the current month.

G. Cost CSV

On Agent Ledger settings, paste a clearly fake CSV for the same month and tools you used, for example:

tool,month,amount_usd copilot,2026-11,100

Use the month you are testing. Click Upload costs. Confirm "Saved 1 cost rows" (a header line is ignored and is not counted). Re-open Apps → Agent Ledger for that month and confirm Agent cost per item is no longer a dash (the App divides that month's uploaded spend by the agent-handled items it has for that tool).

To test validation, upload a broken line such as copilot,not-a-month,100 and confirm the page says "Fix lines: 1" and does not change the saved costs.

H. GitHub webhook settings

Still on the settings page, click Show webhook URL and confirm a URL is shown. Enter 19 characters and click Save secret; confirm the error "secret must be >= 20 chars". Then enter 20 or more random characters, save, and confirm "Webhook secret saved." You do not need to add a real GitHub webhook to finish a product review of the settings UI. If you do add one, use a throwaway secret, not a production credential, and delete the webhook when you are done.

I. Threshold (optional)

Set the attribution threshold to 10 and click Save. After the next nightly sync, a work item whose only signal is a single label (weight 3) should be treated as human. Set the threshold back to 3 when you are finished, and wait for the following sync.

7. FAQ

Why is the Agent Ledger page empty after I install?

The first summary is built by the nightly sync, which also backfills 90 days of updated work items. There is no button to run it early. Check Agent Ledger settings for the last-sync line.

Why does a labeled work item still look human on the panel?

The panel reads stored facts for Jira labels. If the nightly sync has not processed that work item yet, label signals will not appear. Linked pull requests from Jira's development integration can still show when you open the panel.

Which AI tools are detected?

GitHub Copilot, OpenAI Codex, Claude Code, Cursor, and Devin, from the signals in section 5. You can force a tool with a label such as ai-agent:cursor.

Does anything leave Atlassian?

The App does not call servers outside Atlassian. If you opt in to the GitHub webhook, events come in; nothing is sent back to GitHub. Details are in the Privacy Policy and security practices.

How do I uninstall, and what happens to my data?

A Jira admin uninstalls the App from Apps → Manage your apps. Atlassian marks the App's stored data for your site as deleted. If you set up the GitHub webhook, delete it in GitHub as well. See the Privacy Policy for the full description.

8. Help