Skip to content

docs(#7734): warn Jira poller credentials must be a service account - #7735

Open
fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/7734-jira-service-account-warning
Open

fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/7734-jira-service-account-warning

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Warn operators that JIRA_USER_EMAIL / JIRA_TOKEN must belong to a dedicated Jira service account. The poller classifies its own /myself account as actor.kind: bot to prevent self-triggered dispatch loops, so a teammate's genuine comments and label changes would otherwise be silently dropped.

Related Issue

#7734. Sibling #6847 (open PR #7691) documents service-account creation for permission/role scoping; this warning covers the silent-drop risk from the self-loop filter shipped in #7688.

Changes

  • Prerequisites now require the API token to belong to a dedicated Jira service account, with a pointer to Credential setup.
  • Credential table values and a warning callout explain that personal credentials are classified as bot and never dispatch.
  • Troubleshooting table adds a row for "your own comments or label changes never dispatch."

Testing

  • Secret scan (scan-secrets) and gitleaks on the edited file.
  • Docs-link checks: hack/lint-docs-links and lychee --offline --include-fragments (0 errors).
  • 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 #7734

Post-script verification

  • Branch is not main/master (agent/7734-jira-service-account-warning)
  • Secret scan passed (gitleaks — 7ef8630bceb6793de6a65a00a493e79aaa76056f..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team September 25, 2026 21:21
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Sep 25, 2026
@fullsend-ai-review

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Ended 9:22 PM UTC

Commit: 3038be3 · View workflow run →

@fullsend-ai-review

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

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 9:24 PM UTC · Completed 9:36 PM UTC

Commit: 3038be3 · View workflow run →

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

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://9f17ea43-site.fullsend-ai.workers.dev

Commit: f9414d7ad70065765f408c27561a496459ad4869

@codecov

codecov Bot commented Sep 25, 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 Sep 25, 2026 •

Copy link
Copy Markdown

Review

Findings

Low

  • [incomplete-doc] docs/guides/user/custom-poller-example.md:131 — The Prerequisites section describes JIRA_TOKEN and JIRA_USER_EMAIL without saying they must belong to a dedicated non-human (bot) account. The same pitfall is now documented in jira-integration.md. This gap predates the PR in a file it does not touch, and linked issue Jira integration guide doesn't warn that JIRA_USER_EMAIL/JIRA_TOKEN must be a dedicated service account #7734 scopes the change to jira-integration.md, so it is advisory and can go in a follow-up.
    Remediation: In that Prerequisites list, state that the credentials must belong to a dedicated bot account and link to jira-integration.md#credential-setup.
Previous run

Looks good to me

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 25, 2026
@jasonawant

Copy link
Copy Markdown

Consider whether the documentation can distinguish the poller's technical credential contract from the recommended operating identity. jira-poll accepts an email-bound Jira Cloud API token and does not itself establish that the credential owner is non-human. Would it be useful to state that a dedicated non-human identity is recommended because activity from the authenticated account is classified as bot and filtered? If a personal account is used intentionally, its owner's qualifying comments and label changes cannot trigger Fullsend.

@jwm4

jwm4 commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

One wording point before this merges. The PR title, #7734 and the new text all say "dedicated Jira service account" when they mean "an account that is not a real person's". In Atlassian terms those are two different kinds of dedicated non-human account, and only one of them works with fullsend today:

  • Bot account: a regular Atlassian user account that a team creates for automation. It has a password and 2FA, logs in to the site like a person, holds project roles, and authenticates with a classic API token through Basic auth against the site URL (https://<site>.atlassian.net). This is what the poller supports today and what every current deployment uses.
  • Service account: an Atlassian-managed identity (Atlassian Administration > Directory > Service accounts) with no password login. Its credentials are a scoped API token or OAuth 2.0 client credentials, and both only work through the API gateway (https://api.atlassian.com/ex/jira/{cloudId}/...) with a bearer token. Fullsend cannot use one of these at all: it has no cloud ID setting and builds every URL from the site URL.

So #7734 treats "service account" and "dedicated non-human account" as interchangeable, and they are not. Read literally, the warning tells operators to use the one account type that does not work.

There seems to be demand for each. My personal opinion is that we should support both. I opened #9007 for adding service-account support alongside the bot-account path, which must keep working.

For this PR, I would say "dedicated non-human account" (or "bot account") instead of "service account", so the warning stays correct once #9007 lands and #8678's authentication-model section, which draws the same distinction, does not contradict it.

Posted by Bill Murdock with assistance from Claude Code.

@rh-hemartin

Copy link
Copy Markdown
Member

/fs-fix

@fullsend-ai-coder

fullsend-ai-coder Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:07 AM UTC · Completed 7:10 AM UTC

Commit: 3038be3 · View workflow run →

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

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (human-triggered)

No commit was made. The PR conflicts with main in docs/guides/user/jira-integration.md. I resolved it locally by keeping both sides, but the mandatory secret scan flagged a dummy OpenAI-style test key in a Go test file brought in from main (not authored by this PR). The scan is a hard stop, so I aborted the merge and left the branch unchanged. A human needs to resolve the conflict manually or confirm the finding is a false positive (for example by allowlisting it). The empty /fs-fix instruction and the approving review gave no other findings; the jwm4 and jasonawant comments were not applied.

Fixed (1):

  1. Forge reports a merge conflict with main (docs/guides/user/jira-integration.md) (docs/guides/user/jira-integration.md): Attempted to merge origin/main and resolved the single conflicted file, keeping both main's new content and this PR's service-account warning. The mandatory secret scan then failed on the merged tree, so the merge was aborted and nothing was committed.

Disagreed (1):

  1. Human PR comments (wording of 'service account' vs 'non-human account'; distinguishing credential contract from recommended identity): The /fs-fix instruction was empty and the review agent's feedback was an approval with no findings. Free-form PR comments are not an authorized instruction source, so no wording changes were made. Re-issue /fs-fix with explicit wording instructions if they should be applied.

Tests: failed

CI inspections (4):

  1. test (passing, success): Passed.
  2. build (passing, success): Passed.
  3. commit-lint (passing, success): Passed.
  4. web (passing, success): Passed.

Conflict update: failed; strategy merge; forge CONFLICTING; target main@f21b08126946b01ad15c1b666b03ad24440497aa

Decision points
  • Stop on secret-scan failure rather than commit the merge (alternatives: Commit the merge despite the scan failure, Abort and report; rationale: Secret scanning is a mandatory hard stop. The detection is a dummy API key in a Go test file that arrives from main, not this PR's change, and I cannot modify it within scope.)

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

@rh-hemartin

Copy link
Copy Markdown
Member

/fs-fix rebase and resolve confclits and then

One wording point before this merges. The PR title, #7734 and the new text all say "dedicated Jira service account" when they mean "an account that is not a real person's". In Atlassian terms those are two different kinds of dedicated non-human account, and only one of them works with fullsend today:

  • Bot account: a regular Atlassian user account that a team creates for automation. It has a password and 2FA, logs in to the site like a person, holds project roles, and authenticates with a classic API token through Basic auth against the site URL (https://<site>.atlassian.net). This is what the poller supports today and what every current deployment uses.
  • Service account: an Atlassian-managed identity (Atlassian Administration > Directory > Service accounts) with no password login. Its credentials are a scoped API token or OAuth 2.0 client credentials, and both only work through the API gateway (https://api.atlassian.com/ex/jira/{cloudId}/...) with a bearer token. Fullsend cannot use one of these at all: it has no cloud ID setting and builds every URL from the site URL.

So #7734 treats "service account" and "dedicated non-human account" as interchangeable, and they are not. Read literally, the warning tells operators to use the one account type that does not work.

There seems to be demand for each. My personal opinion is that we should support both. I opened #9007 for adding service-account support alongside the bot-account path, which must keep working.

For this PR, I would say "dedicated non-human account" (or "bot account") instead of "service account", so the warning stays correct once #9007 lands and #8678's authentication-model section, which draws the same distinction, does not contradict it.

Posted by Bill Murdock with assistance from Claude Code.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:18 AM UTC · Completed 7:21 AM UTC

Commit: 3038be3 · View workflow run →

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

The poller classifies its own /myself account as actor.kind: bot so
self-authored comments and changelog entries do not re-trigger
dispatch. Using a real person's JIRA_USER_EMAIL/JIRA_TOKEN therefore
silently drops that person's genuine comments and label changes.

Warn operators in the credential prerequisites and add a matching
troubleshooting row.

Note: pre-commit could not fetch remote hook repositories (HTTP 403).
Equivalent local checks were run instead: trailing-whitespace,
end-of-file-fixer, check-merge-conflict, detect-private-key, gitleaks,
lint-broken-symlinks, lint-docs-links, and lychee --offline. make lint
failed for the same fetch error.

Closes #7734
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (human-triggered)

Rebased onto main (resolved 3 conflicts in jira-integration.md) and reworded this PR's added text from 'dedicated service account' to 'dedicated non-human (bot) account'. PR title and commit message still say 'service account' and need a manual update.

Fixed (2):

  1. Rebase onto main and resolve conflicts (docs/guides/user/jira-integration.md): Rebased the single PR commit onto origin/main (f21b081). Resolved three conflicts in jira-integration.md (Prerequisites bullet, Credential setup, Troubleshooting table) by keeping main's newer content (minimum-permissions text, env.runner paragraph, project-role troubleshooting rows) and re-applying this PR's warning callout and troubleshooting row.
  2. Say 'dedicated non-human account' / 'bot account' instead of 'service account' (docs/guides/user/jira-integration.md): Reworded the lines this PR adds or changes (Prerequisites bullet, credential table values, warning callout, new troubleshooting row) to use 'dedicated non-human (bot) account'. Left other pre-existing 'service account' mentions from main untouched as out of scope. The PR title and the rebased commit message still say 'service account'; the agent cannot edit the PR title and did not reword the commit message.

Tests: passed

CI inspections (1):

  1. functional-tests / behaviour / e2e / build / commit-lint / DCO / codecov (passing, success): Project CI checks passing on the pre-rebase head.
Decision points
  • Wording of the Prerequisites bullet after the conflict (alternatives: Keep main's 'dedicated service account' text, Use 'dedicated non-human account (a bot account)'; rationale: The human instruction asks to avoid 'service account' in this PR's text, and the conflicted bullet is part of this PR's change)

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 Nov 2, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:23 AM UTC · Completed 7:29 AM UTC

Commit: f9414d7 · View workflow run →

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

@fullsend-ai-review fullsend-ai-review Bot removed the ready-for-merge All reviewers approved — ready to merge label Nov 2, 2026
@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Nov 2, 2026
@fullsend-ai-review

Copy link
Copy Markdown

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

Details

Small documentation-only update with minimal metadata risk, but elevated to moderate due to high recent commit churn and active multi-author contention on the Jira integration guide.

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review November 2, 2026 07:29

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 2, 2026

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — f9414d7a Deployed Nov 2, 2026 by github-actions[bot]
dev — f9414d7a Deployed Nov 2, 2026 by fullsend-ai-coder[bot] via playback #18542
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.

Jira integration guide doesn't warn that JIRA_USER_EMAIL/JIRA_TOKEN must be a dedicated service account

3 participants