Skip to content

docs(#6847): add a setup overview to the Jira integration guide - #7691

Merged
ralphbean merged 3 commits into
mainfrom
agent/6847-jira-setup-overview
Sep 28, 2026
Merged

ralphbean merged 3 commits into
mainfrom
agent/6847-jira-setup-overview

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Add a six-step setup overview at the top of the Jira integration guide so operators can see the whole path before diving into polling internals.

Related Issue

#6847 (setup TL;DR). Sibling #6846 still tracks trimming the implementation-heavy sections of the same guide.

Changes

  • New Setup overview covering: Jira service account, Developers + Administrators project roles, GitHub install, poller workflow, project/JQL, and per-agent trigger expressions.
  • Call out that one account holding both project roles is more power than we want long-term.
  • Mark the trigger-expression step as temporary until built-in harnesses ship native Jira triggers (jira-poll: built-in harness files lack CEL triggers, causing 0 dispatches #6672).
  • Align Prerequisites and Repo configuration with that picture so they no longer understate the role requirement or claim no harness changes are needed.

Testing

  • Docs-link checks: hack/lint-docs-links and lychee --offline --include-fragments on the edited guide (0 errors).
  • Secret scan (scan-secrets) and gitleaks on the edited file.
  • make lint — pre-commit run could not fetch remote hook repos (HTTP 403). Equivalent local markdown hooks were run instead.
  • Tests added/updated for new or modified logic — documentation only; no production code change.

Checklist

  • PR title follows Conventional Commits (docs type, issue-number scope)
  • Commits are not signed off (autonomous agent; DCO app auto-skips)
  • I wrote this contribution myself and can explain all changes in it

Closes #6847

Post-script verification

  • Branch is not main/master (agent/6847-jira-setup-overview)
  • Secret scan passed (gitleaks — 3871d1b17c2a81f763156ab97b89c4c90d80acf3..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

The Jira guide jumped into polling internals before operators could
see the end-to-end setup. Add a six-step overview at the top covering
the service account, dual project roles, GitHub install, poller
workflow, project/JQL, and per-agent trigger expressions.

Call out that one account holding both Developers and Administrators
is more power than we want long-term, and that the trigger step is
temporary until built-in harnesses ship native Jira triggers (#6672).

Align Prerequisites and Repo configuration with that picture so they
do not contradict the overview.

Note: pre-commit could not fetch remote hook repos (HTTP 403). Ran
equivalent local checks instead: trailing-whitespace, end-of-file,
lint-docs-links, lychee, gitleaks, and scan-secrets.

Closes #6847
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team September 24, 2026 19:30
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Sep 24, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:32 PM UTC · Completed 7:46 PM UTC

Commit: a4498d1 · View workflow run →

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

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://5fd37c65-site.fullsend-ai.workers.dev

Commit: ab55356e27397a65489489d56f14d38f2045258c

@codecov

codecov Bot commented Sep 24, 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-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Sep 24, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Low-risk additive documentation change directly addressing the linked issue (Tier 1 = 1.00, Tier 3 = 1.33); historical git churn and regression-fix frequency on this guide keep Tier 2 at 2.86, producing a composite of 1.62 that rounds to 2 (moderate), unchanged from the prior review of this PR.

Previous run

Risk Assessment: moderate (2/5)

Details

Low-risk additive documentation change directly addressing the linked issue and its own prior review finding (Tier 1 = 1.0, Tier 3 = 1.33); historical git churn/regression-fix frequency on this guide keeps Tier 2 at 2.86, producing a composite of 1.63 that rounds to 2 (moderate), unchanged from the prior review of this PR.

Previous run (2)

Risk Assessment: moderate (2/5)

Details

Low-risk additive documentation change directly addressing the linked issue (Tier 1 = 1.0, Tier 3 = 1.33), but historical git churn and regression-fix frequency on this guide elevate Tier 2 to 2.86, producing a composite of 1.63 that rounds to 2 (moderate).

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Looks good to me

Previous run

Looks good to me

Previous run (2)

Review

Findings

Medium

  • [logic-error] docs/guides/user/jira-integration.md:84 — The new "Repo configuration" sentence tells operators who already have .fullsend/config.yaml to "add the Jira trigger expressions from step 6" — which reads as "put trigger: in config.yaml." config.AgentEntry (internal/config/config.go) has no Trigger field (only Name/Source/Ref/Enabled/Runtime/Model/Effort/Subagents), and per-repo config is decoded with plain yaml.Unmarshal (no strict/KnownFields mode), so a trigger: key placed on a config.yaml agents: entry is silently dropped — no parse error, no warning. trigger is actually a field on Harness (internal/harness/harness.go), i.e. it belongs in a harness YAML file registered via config.yaml's agents[].source (the base: composition pattern documented in customizing-agents.md), not in config.yaml itself. ListTriggeredHarnesses skips any harness whose Trigger is empty, so a reader who follows this sentence literally still gets zero dispatches — the exact "0 dispatches" failure this PR is trying to help operators avoid, now caused by the doc's own new guidance rather than by the missing-native-triggers gap (jira-poll: built-in harness files lack CEL triggers, causing 0 dispatches #6672) it correctly names elsewhere. Step 6 itself (line 20) has the same gap: it says to "add a trigger expression on each agent" and links cel-triggers-reference.md and customizing-agents.md, but never states outright that the expression goes in a harness file, not config.yaml.
    Remediation: Reword line 84 (and reinforce step 6) to name the harness file explicitly, e.g.: "If your repo already has a .fullsend/config.yaml from fullsend github setup, add a harness override with the Jira trigger expressions from step 6 (see Configuring agent behavior) and you are ready to receive dispatches."

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.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:48 PM UTC · Completed 7:53 PM UTC

Commit: a4498d1 · View workflow run →

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

…sions

Reviewer flagged that "add the trigger expressions from step 6" reads as
"put trigger: in config.yaml", but AgentEntry has no Trigger field and
config.yaml is decoded without strict/KnownFields mode, so the key would
silently be dropped. trigger belongs on a Harness YAML file registered via
config.yaml's agents[].source. Reword step 6 and the Repo configuration
paragraph to say so explicitly and link the base: composition section.

Addresses #7691
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (bot-triggered)

Confirmed the single medium-severity finding against internal/config/config.go and internal/harness/harness.go, then reworded the two affected passages in the Jira integration guide to name the harness file explicitly instead of implying config.yaml, matching the reviewer's remediation.

Fixed (1):

  1. Step 6 and the Repo-configuration paragraph tell operators to add a trigger expression without saying where it goes, reading as if it belongs in .fullsend/config.yaml (docs/guides/user/jira-integration.md): Verified AgentEntry (internal/config/config.go) has no Trigger field and config.yaml is decoded with plain yaml.Unmarshal (no strict/KnownFields mode), so a trigger key there is silently dropped, while Harness (internal/harness/harness.go) does define Trigger and ListTriggeredHarnesses skips harnesses with an empty one. Reworded step 6 (line 20) and the Repo configuration paragraph (line 84) to state explicitly that trigger belongs in a harness YAML file registered via config.yaml's agents[].source, and linked customizing-agents.md's base: composition section, per the reviewer's suggested wording.

Tests: passed

CI inspections (12):

  1. behaviour (passing, success)
  2. build (passing, success)
  3. codecov/patch (passing, success)
  4. commit-lint (passing, success)
  5. test (passing, success)
  6. web (passing, success)
  7. functional-tests (passing, success)
  8. e2e (passing, success)
  9. test-sandbox-darwin (passing, success)
  10. vouch-gate (passing, success)
  11. gate (passing, success)
  12. DCO (passing, success)

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 Sep 24, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:55 PM UTC · Completed 8:05 PM UTC

Commit: 31d6bfa · View workflow run →

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

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Sep 24, 2026
Comment thread docs/guides/user/jira-integration.md Resolved
Signed-off-by: Ralph Bean <rbean@redhat.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 25, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:48 PM UTC · Completed 8:59 PM UTC

Commit: ab55356 · View workflow run →

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

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review September 25, 2026 20:59

Superseded by updated review

@ralphbean
ralphbean added this pull request to the merge queue Sep 28, 2026
Merged via the queue into main with commit 0b4dc75 Sep 28, 2026
42 checks passed
@ralphbean
ralphbean deleted the agent/6847-jira-setup-overview branch September 28, 2026 20:35
@fullsend-ai-retro

fullsend-ai-retro Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

🤖 Finished Retro · ✅ Success · Started 8:37 PM UTC · Completed 8:45 PM UTC

Commit: ab55356 · View workflow run →

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

@fullsend-ai-retro

Copy link
Copy Markdown

PR #7691 (docs-only, six-step Jira setup overview) is a healthy example of the pipeline working as intended. The first review pass correctly flagged a real medium-severity logic error (the doc implied trigger belongs in config.yaml, which would silently no-op per AgentEntry/yaml.Unmarshal behavior); the fix agent resolved it correctly in one iteration ($0.81, ~5 min), and a re-review confirmed it. The only miss: across two full review passes (on commits 31d6bfa and ab55356) the review agent said 'Looks good to me' to a self-referential filler sentence ('Six steps, in order... scan this list first, then jump to what you need') that human reviewer ralphbean caught instantly and removed with a one-word inline comment ('Slop.') and a chore: remove slop commit. Neither the docs-currency sub-agent (scoped to staleness: stale/missing/incorrect/incomplete-doc) nor style-conventions (explicitly excludes 'documentation content') owns this class of issue — the repo's own writing-user-docs skill says 'omit needless words' but its 'Common Mistakes' table has no entry for meta-commentary/throat-clearing prose, so neither the writer nor the reviewer was positioned to catch it.

I checked whether this is a recurring pattern: a full-history search of fullsend-ai/fullsend commits and ~100 agent-branch docs PRs found no other instance of a human stripping bot-added self-referential filler — PR #7691 is the only confirmed case so far. I also checked for existing coverage before proposing anything: this exact gap is already tracked by two open issues I am treating as sufficient — fullsend-ai/agents#732 ('Add a consistent agent voice via hardikpandya/stop-slop skill integration', generation-side fix for filler prose/AI-isms across all agents) and #2616 ('Review agent should assess content quality and redundancy in agent-facing documents', a review-side content-quality dimension proposal — currently scoped to skill/agent-definition files, not general user docs, but mechanistically the same gap this PR evidences). fullsend-ai/agents#370 is the broader umbrella tracking verbose/low-value agent output. Given a single occurrence and pre-existing open issues covering both the generation-side and review-side fix, I'm not filing a new proposal — this PR is useful corroborating evidence that #732/#2616's scope should eventually extend to user-facing docs content, not just agent-facing ones, but that's a scoping note for whoever picks those up rather than a new ticket.

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — ab55356e Deployed Sep 25, 2026 by github-actions[bot]
dev — ab55356e Deployed Sep 25, 2026 by ralphbean via behaviour #14072
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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.

docs(jira): add a setup TL;DR to the integration guide

1 participant