Skip to content

docs(#6094): add multi-repo polling section to Jira guide - #6103

Merged
ralphbean merged 2 commits into
mainfrom
agent/6094-multi-repo-polling-docs
Aug 17, 2026
Merged

docs(#6094): add multi-repo polling section to Jira guide#6103
ralphbean merged 2 commits into
mainfrom
agent/6094-multi-repo-polling-docs

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Adds a "Multi-repo polling" section to the Jira integration guide (docs/guides/user/jira-integration.md) addressing deployment questions identified during ROSAENG onboarding. The section covers whether each repo needs its own poll workflow, how entity property locks namespace across repos, and how the 50-candidate cap interacts with multiple pollers.

Related Issue

Split from #6076; related to #5903 (backfill window documentation).

Changes

  • Added "Multi-repo polling" section with three subsections:
    • Should each repo have its own poll workflow? — explains that --target-repo controls entity property namespace and GHA concurrency group isolation
    • How entity property locks namespace across repos — concrete example showing two repos polling the same Jira issue with separate property keys
    • 50-candidate cap with multiple repos — clarifies the cap is per-poller, not global, with operational guidance for large deployments (JQL scoping, cron staggering, rate limit monitoring)
  • Placed after the existing "Poll coordination" section (which introduces the namespacing concept) and before "Troubleshooting"

Testing

  • lychee link checker passes — all 15 links in the file resolve correctly
  • No secrets detected (scan-secrets)
  • gitlint passes on the commit message

Closes #6094

Post-script verification

  • Branch is not main/master (agent/6094-multi-repo-polling-docs)
  • Secret scan passed (gitleaks — d62fc7141712252d51853fa6a9be5af6b929251b..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

Add a "Multi-repo polling" section to the Jira integration guide
answering deployment questions identified during ROSAENG onboarding:

- Whether each repo needs its own poll workflow (yes — the
  --target-repo flag controls entity property namespace and the
  GHA concurrency group provides natural isolation)
- How entity property locks namespace across repos via the
  {owner}.{repo} key prefix, with a concrete two-repo example
- How the 50-candidate cap interacts with N pollers (per-poller,
  not global) and operational considerations for large deployments
  (JQL scoping, cron staggering, rate limit monitoring)

Closes #6094
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team as a code owner August 11, 2026 14:35
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Aug 11, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 11, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 2:36 PM UTC · Completed 2:48 PM UTC

Commit: 11347ae · View workflow run →

@github-actions

github-actions Bot commented Aug 11, 2026

Copy link
Copy Markdown

Site preview

Preview: https://6e0d11ae-site.fullsend-ai.workers.dev

Commit: c62953f1c4c41ef1a39759d62e606d51f9a290c0

@codecov

codecov Bot commented Aug 11, 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 commented Aug 11, 2026

Copy link
Copy Markdown

Review

Findings

Low

  • [technical accuracy] docs/guides/user/jira-integration.md — The GHA concurrency group explanation states the workflow's concurrency.group "is scoped to the workflow file, which lives in the repo." In reality, the concurrency group is a static string (fullsend-jira-poll), and it works independently across repos because GitHub Actions concurrency groups are inherently per-repository. The conclusion is correct but the reasoning could confuse readers who examine the workflow YAML and see a plain string with no file-path component.
    Remediation: Reword to clarify that GitHub Actions scopes concurrency groups to the repository, rather than implying the group name incorporates the workflow file path.
Previous run

Looks good to me


Labels: PR adds documentation to docs/guides/user/, modifying only a user guide

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge component/docs User-facing documentation labels Aug 11, 2026
Comment thread docs/guides/user/jira-integration.md Outdated
@ralphbean

Copy link
Copy Markdown
Member

/fs-fix address the one finding above

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 5:26 PM UTC · Completed 5:32 PM UTC

Commit: 11347ae · View workflow run →

…ling

Moves the advice about using Jira Components or labels to segment
projects per repo from a buried bullet point into the section
introduction, making it a clear best practice recommendation.

Addresses review feedback on #6103
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (human-triggered)

Addressed 1 review finding: promoted JQL scoping advice (using Jira Components or labels) from a buried bullet to an up-front best practice in the Multi-repo polling section introduction.

Fixed (1):

  1. Promote JQL scoping with Jira Components/labels as up-front best practice (docs/guides/user/jira-integration.md): Added recommendation to use Jira Components or labels to segment the project in the Multi-repo polling section introduction, promoting it from a buried bullet to an up-front best practice. Also updated the existing bullet to reference Components alongside labels with concrete JQL examples (component = Frontend, labels = frontend).

Tests: passed

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 Aug 11, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 5:33 PM UTC · Completed 5:45 PM UTC

Commit: c62953f · View workflow run →

@ralphbean
ralphbean added this pull request to the merge queue Aug 17, 2026
Merged via the queue into main with commit 3a3c02e Aug 17, 2026
17 of 18 checks passed
@ralphbean
ralphbean deleted the agent/6094-multi-repo-polling-docs branch August 17, 2026 21:00
@fullsend-ai-retro

fullsend-ai-retro Bot commented Aug 17, 2026

Copy link
Copy Markdown

🤖 Finished Retro · ✅ Success · Started 9:03 PM UTC · Completed 9:19 PM UTC

Commit: c62953f · View workflow run →

@fullsend-ai-retro

Copy link
Copy Markdown

Retro: PR #6103 — docs(#6094): add multi-repo polling section to Jira guide

Workflow chain: Issue #6094triage (4.5 min) → code (7.5 min) → review #1 (12 min, LGTM) → human feedback → fix (7 min) → review #2 (13 min, 1 low finding, approved) → human approval → merged.

Outcome: Clean workflow. Docs-only PR, 1 file changed, 41 lines added. Two commits (original + fix addressing human editorial feedback). Merged in one fix iteration.

Observations

  1. Review finding inconsistency (evidence for agents#830): Review docs: Add agent-compatible code problem document #1 on commit 11347ae found no issues. Review Add problem areas: Tekton pipeline review, migration path, multi-tenancy #2 on commit c62953f caught a low-severity technical accuracy issue about GHA concurrency group scoping — on text that was present and unchanged since the first commit. This matches the pattern in agents#830: the correctness sub-agent runs at constrained scope on first reviews of docs/mechanical changes but gets full scope on re-reviews, causing findings to appear only on subsequent passes.

  2. Human review caught an editorial improvement the review agent didn't: The human reviewer identified that JQL scoping advice (using Jira Components/labels to segment projects per repo) should be promoted from a buried bullet to an up-front best practice. This is subjective editorial judgment about content organization — not systematically catchable by the review agent and not actionable as an agent improvement.

  3. Low-severity finding shipped unaddressed: The concurrency group wording (stating the group "is scoped to the workflow file" when it is actually a static string scoped per-repository by GitHub Actions) was flagged by Review Add problem areas: Tekton pipeline review, migration path, multi-tenancy #2 but approved as low severity. The human also approved with the finding visible. This is the review system working as designed — low-severity findings are informational, not blocking.

No new proposals

All observations map to existing open issues. No new proposals warranted.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(jira): document multi-repo polling patterns

1 participant