Skip to content

docs(#8920): describe Jira triage and code results in Jira guide - #8943

Merged
ggallen merged 2 commits into
mainfrom
agent/8920-jira-result-docs
Oct 30, 2026
Merged

ggallen merged 2 commits into
mainfrom
agent/8920-jira-result-docs

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Updates docs/guides/user/jira-integration.md so it matches current behavior. Built-in triage and code agents now write their results to the Jira issue that started the run, and code artifacts stay on the GitHub or GitLab code host. This removes the stale claims that built-in agents "have not been adapted", that output goes to GitHub, and that dispatched runs fail until #2264.

Related Issue

#8920. The implementation landed in fullsend-ai/agents#1843. The work-item identity landed in #8922 (#2264).

Changes

  • New Where built-in agent results appear subsection under Event semantics:
    • a table of what each stage writes to Jira and what stays on the code host
    • the routing and identity checks
    • configured transition names (JIRA_*_TRANSITION, with issues: add tracker-neutral issue transitions #6704 for tracker-neutral transitions)
    • the Not applied in Jira reporting
    • retry idempotency (fixed markers and run-scoped markers)
    • write failures fail the step
    • bot-loop protection
    • runner-only Jira credentials
  • Repo configuration: replaced the "output goes to GitHub / runs will not complete (Preserve Jira work-item identity through agent execution #2264)" text with a short pointer to the new subsection.
  • Credential setup: notes that the built-in triage and code harnesses declare JIRA_TOKEN/JIRA_USER_EMAIL under env.runner in their Jira overlays.
  • GitLab runtime → Requirements: agent jobs need the Jira variables for results as well as run status.
  • Troubleshooting: replaced the Preserve Jira work-item identity through agent execution #2264 "fails immediately" row with two rows. One covers agents pinned to a release older than the Jira result writes. The other covers a code step that fails on the Jira write after the PR/MR exists.

I checked each claim against agents#1843 (docs/code.md, docs/triage.md, harness/code.yaml, and the post-script diffs) and against the agents harness/triage.yaml Jira overlay. The "release that follows v0.52.0" wording is there because #1843 merged after v0.52.0, which is the latest agents release.

Testing

  • Ran the applicable hooks directly, because pre-commit could not fetch hook repos in the sandbox (TLS verification error). These were pre-commit-hooks v6.0.0 checks (end-of-file, trailing whitespace, private key, merge conflict, mixed line ending), gitleaks via scan-secrets, hack/lint-docs-links, hack/lint-broken-symlinks, and lychee --offline --include-fragments (0 errors, including the new anchor).
  • Tests added/updated: not applicable (docs only)

Checklist

🤖 Generated with Claude Code


Closes #8920

Post-script verification

  • Branch is not main/master (agent/8920-jira-result-docs)
  • Secret scan passed (gitleaks — 0f0a0cbd434c80a2071bef1282ffe94941d22842..HEAD)
  • PR body secret scan passed (gitleaks — no-git)
  • Final PR description secret scan passed (gitleaks — no-git)

The Jira guide still said built-in agents had not been adapted to
Jira-sourced runs, that substantive output went to GitHub, and that
dispatched runs would fail until #2264 landed. #2264 shipped the
work-item identity, and fullsend-ai/agents#1843 made triage and code
write their results to the originating Jira issue.

Replace the stale passages in the event-semantics section, the repo
configuration paragraph, and the Troubleshooting table with a "Where
built-in agent results appear" subsection. It states which results go
to Jira (triage comment, labels, components, configured transitions,
and the code-stage update with the PR/MR link) and which artifacts stay
on the GitHub or GitLab code host. It also covers retry idempotency,
visible write failures, bot-loop protection, and runner-only Jira
credentials. Each claim was checked against agents#1843 and the agents
triage and code harnesses.

pre-commit could not fetch hook repositories (TLS verification error),
so the applicable hooks were run directly: pre-commit-hooks checks,
gitleaks via scan-secrets, lint-docs-links, lint-broken-symlinks, and
lychee.

Closes #8920

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 12:43 PM UTC · Completed 12:55 PM UTC

Commit: 843136d · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.97

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://da1561df-site.fullsend-ai.workers.dev

Commit: 1c10a417db3c37ded575fb642b46ad753eff9ed5

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Oct 30, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Documentation update across three files by a bot with matching issue scope, with moderate risk driven by high recent churn and coupling on the active Jira integration guide.

Previous run

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Single-file documentation update by a bot with matching issue scope, with moderate risk driven by high recent churn and coupling on the active Jira integration guide.

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Looks good to me

Earlier findings

  • docs/guides/user/jira-integration.md:111, api-contract, resolved — the claim that Jira does not create labels on demand now reads "triage does not create new labels".
  • docs/guides/user/jira-integration.md:157, doc-style, resolved — the env.runner paragraph is rewrapped to the Markdown line-wrapping rule.
  • docs/guides/user/jira-integration.md:170, doc-style, resolved — the Repo configuration paragraph is rewrapped.
  • docs/guides/user/issues-commands.md:9, incomplete-doc, resolved — the text now says the pipeline posts comments for Jira-sourced triage and code runs.
  • docs/guides/user/adoption.md:101, stale-doc, resolved — the Jira triage-bridge example is replaced with a tracker other than GitHub, GitLab, or Jira.

Labels: PR changes user-facing documentation

Previous run

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6ImFwaS1jb250cmFjdCIsImZpbGUiOiJkb2NzL2d1aWRlcy91c2VyL2ppcmEtaW50ZWdyYXRpb24ubWQiLCJpZCI6ImZfZjg0MDYyNzc2NmY0MjJmOSIsImxpbmUiOjExMSwiYWN0aW9uYWJsZSI6dHJ1ZX0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoiZG9jLXN0eWxlIiwiZmlsZSI6ImRvY3MvZ3VpZGVzL3VzZXIvamlyYS1pbnRlZ3JhdGlvbi5tZCIsImlkIjoiZl9lNzExNTRiYTY1ZjYwYzU4IiwibGluZSI6MTU3LCJhY3Rpb25hYmxlIjp0cnVlfSx7InNldmVyaXR5IjoibG93IiwiY2F0ZWdvcnkiOiJkb2Mtc3R5bGUiLCJmaWxlIjoiZG9jcy9ndWlkZXMvdXNlci9qaXJhLWludGVncmF0aW9uLm1kIiwiaWQiOiJmXzNkMjUyYzM1YzgzZDRhMmYiLCJsaW5lIjoxNzAsImFjdGlvbmFibGUiOnRydWV9LHsic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6ImluY29tcGxldGUtZG9jIiwiZmlsZSI6ImRvY3MvZ3VpZGVzL3VzZXIvaXNzdWVzLWNvbW1hbmRzLm1kIiwiaWQiOiJmXzQyODIyY2JjNGQ3OWExNWUiLCJsaW5lIjo5LCJhY3Rpb25hYmxlIjp0cnVlfSx7InNldmVyaXR5IjoibG93IiwiY2F0ZWdvcnkiOiJzdGFsZS1kb2MiLCJmaWxlIjoiZG9jcy9ndWlkZXMvdXNlci9hZG9wdGlvbi5tZCIsImlkIjoiZl80YmE4Mjc5MzUyNTA2YjNkIiwibGluZSI6MTAxLCJhY3Rpb25hYmxlIjp0cnVlfV19 -->

Review

Findings

Low

  • [api-contract] docs/guides/user/jira-integration.md:111 — The parenthetical "(Jira does not create labels on demand)" attributes the restriction to Jira. Jira Cloud labels are free-form, so this is a limit of the built-in triage post-script (upstream agents docs/triage.md says "labels are not auto-created"), not of Jira. The described behavior (reported under Not applied in Jira) is accurate; only the stated cause is wrong.
    Remediation: Present it as a triage limitation, e.g. "(triage does not create new labels)".
  • [doc-style] docs/guides/user/jira-integration.md:157 — The edited env.runner paragraph stays a single ~490-character line. docs/contributing/documentation.md requires wrapping near 80 columns, and rewrapping a paragraph you are already editing.
    Remediation: Wrap the paragraph at word boundaries near 80 columns.
  • [doc-style] docs/guides/user/jira-integration.md:170 — The rewritten "Repo configuration" paragraph stays a single ~800-character line, with the same rewrap-on-edit rule.
    Remediation: Wrap the paragraph at word boundaries near 80 columns.
  • [incomplete-doc] docs/guides/user/issues-commands.md:9 — "The built-in agent pipeline handles comment posting automatically for GitHub-sourced events" omits Jira-sourced triage and code runs, which this PR documents as now writing to Jira.
    Remediation: Say the built-in pipeline posts automatically for GitHub-sourced events and for Jira-sourced triage and code runs.
  • [stale-doc] docs/guides/user/adoption.md:101 — "a triage agent that bridges to Jira" is given as an example of a custom agent for tooling the default agents don't cover. The built-in triage agent now writes results to Jira.
    Remediation: Replace the example with tooling the built-in agents still don't cover.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@codecov

codecov Bot commented Oct 30, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-coder

fullsend-ai-coder Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 12:57 PM UTC · Completed 1:00 PM UTC

Commit: 843136d · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $0.31

- jira-integration: attribute the label-creation limit to triage, not Jira
- jira-integration: wrap the edited env.runner and Repo configuration paragraphs
- issues-commands: mention Jira-sourced triage and code runs
- adoption: drop the Jira triage-bridge example now covered by built-in triage

Note: pre-commit hooks could not run via pre-commit (hook repos could not be
fetched, certificate error). Ran the applicable local hooks directly
(lint-docs-links, lychee offline link check); both passed.

Addresses #8943

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (bot-triggered)

Addressed all five low-severity documentation findings. Project CI was passing, so no CI-driven edits were needed. Pre-commit could not fetch hook repositories, so the applicable local docs hooks (link scope and offline link check) were run directly and passed.

Fixed (5):

  1. Label-creation limit wrongly attributed to Jira (docs/guides/user/jira-integration.md): Reworded the parenthetical to say triage does not create new labels.
  2. env.runner paragraph not wrapped near 80 columns (docs/guides/user/jira-integration.md): Wrapped the paragraph at word boundaries.
  3. Repo configuration paragraph not wrapped near 80 columns (docs/guides/user/jira-integration.md): Wrapped the paragraph at word boundaries, keeping link targets intact.
  4. issues-commands omits Jira-sourced triage and code runs (docs/guides/user/issues-commands.md): Stated that the built-in pipeline posts automatically for GitHub-sourced events and for Jira-sourced triage and code runs.
  5. adoption example of a triage agent bridging to Jira is stale (docs/guides/user/adoption.md): Replaced it with a triage agent for a tracker other than GitHub, GitLab, or Jira.

Tests: passed

CI inspections (6):

  1. CI / test (passing, success)
  2. CI / commit-lint (passing, success)
  3. CI / gateway-doc-configs (passing, success)
  4. E2E Tests / behaviour (passing, success)
  5. codecov/patch (passing, success)
  6. DCO (passing, success)

Conflict update: skipped; strategy none; forge MERGEABLE; target main

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 1:02 PM UTC · Completed 1:08 PM UTC

Commit: 1c10a41 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.25

@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge component/docs User-facing documentation labels Oct 30, 2026
@ggallen
ggallen enabled auto-merge October 30, 2026 13:37
@ggallen
ggallen added this pull request to the merge queue Oct 30, 2026
Merged via the queue into main with commit 5a171e0 Oct 30, 2026
64 checks passed
@ggallen
ggallen deleted the agent/8920-jira-result-docs branch October 30, 2026 13:41

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 1c10a417 Deployed Oct 30, 2026 by github-actions[bot]
dev — 1c10a417 Deployed Oct 30, 2026 by fullsend-ai-coder[bot] via playback #18349
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/docs User-facing documentation ready-for-merge All reviewers approved — ready to merge ready-for-review Triggers review agent dispatch risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write triage and code results to the Jira work item

1 participant