Skip to content

docs(#4885): document Jira auth model, token rotation, migration - #8678

Open
fullsend-ai-coder[bot] wants to merge 3 commits into
mainfrom
agent/4885-jira-auth-strategy-docs
Open

fullsend-ai-coder[bot] wants to merge 3 commits into
mainfrom
agent/4885-jira-auth-strategy-docs

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Updates docs/guides/user/jira-integration.md with the parts of #4885 that were still missing:

  • An authentication model that separates three things: what fullsend implements today, the account we recommend running it under, and Atlassian-managed service accounts (not supported yet).
  • A credential rotation procedure.
  • A migration path off long-lived API tokens.

Related Issue

#4885. The data-leakage assessment is still tracked in #2513, which the new docs link to.

Changes

  • Authentication model (new section):
    • Current contract: HTTP Basic with JIRA_USER_EMAIL + JIRA_TOKEN against <JIRA_BASE_URL>/rest/api/3, with /myself used for bot self-filtering. Checked against internal/forge/jira/client.go and its callers (internal/cli/poll.go, jira_tracker.go, tracker_client.go), which all require an email.
      • The library's Bearer branch can't be reached from the CLI, so the doc doesn't mention it.
    • Recommended identity: a dedicated non-human Atlassian user account, with the reasons why.
    • Atlassian-managed service accounts: scoped API tokens and OAuth 2.0 client credentials through api.atlassian.com/ex/jira/{cloudId}. Fullsend doesn't support these yet (no cloudId, URLs built from the site URL, sandbox egress limited to *.atlassian.net).
    • Data exposure: a short note linking Document Jira data leakage risks for public repository configurations #2513.
  • Rotating the Jira API token (new section):
    • Where copies of the token live: every repo or org JIRA_TOKEN secret, the pre-encoded atlassian-cloud sandbox credential, and local shells.
    • A zero-downtime procedure that checks the new token with /myself before deploying it.
    • What to do differently after a suspected leak.
  • Migration path to short-lived credentials (new section):
    • OAuth client credentials as the target.
    • Why that is not workload-identity federation (the client secret is still long-lived).
    • The code work it needs, including revalidating each Jira operation the client performs today.
  • Wording fixes: the ambiguous "service account" wording in the setup overview, prerequisites and bot-filtering paragraph now says "dedicated (non-human) account". The 401 troubleshooting row now links to the rotation section.

Testing

  • make lint (pre-commit run) could not fetch remote hook repos in the sandbox (TLS failure). The hooks that apply to Markdown were run directly and passed: trailing-whitespace, end-of-file, mixed-line-ending and merge-conflict checks, hack/lint-docs-links, hack/lint-broken-symlinks, lychee --offline --include-fragments (all new anchors resolve), and gitleaks via scan-secrets.
  • Tests added/updated for new or modified logic: not applicable, docs only.

Caveat: the statements about Atlassian service accounts (gateway URL, OAuth token exchange, short-lived Bearer tokens) follow Atlassian's documentation as cited in the issue thread. The sandbox had no network access to re-check them, so a reviewer may want to compare them against the linked Atlassian pages.

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO): not applicable, autonomous agent commit
  • I wrote this contribution myself and can explain all changes in it

🤖 Generated with Claude Code


Closes #4885

Post-script verification

  • Branch is not main/master (agent/4885-jira-auth-strategy-docs)
  • Secret scan passed (gitleaks — 3a098356a46d2367a73eef876294981d57d15455..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

The Jira guide called the poller identity a "service account" without
saying which kind, gave only a one-line rotation tip, and did not say
how fullsend could move off long-lived API tokens.

Add to docs/guides/user/jira-integration.md:

- Authentication model: the current contract (HTTP Basic with
  JIRA_USER_EMAIL + JIRA_TOKEN against <site>/rest/api/3, checked
  against internal/forge/jira/client.go and the poll, tracker and
  run-status callers), the recommended dedicated non-human account, and
  Atlassian-managed service accounts (scoped tokens, OAuth 2.0 client
  credentials via api.atlassian.com/ex/jira/{cloudId}), which fullsend
  does not support yet. Includes a data-exposure note linking #2513.
- Rotating the Jira API token: where copies live (per-repo secrets, the
  pre-encoded atlassian-cloud sandbox credential), a zero-downtime
  procedure, and leak handling.
- Migration path: OAuth client credentials as the target, why it is not
  workload-identity federation, and the code work it needs (auth
  abstraction, cloudId config, sandbox egress, revalidating each Jira
  operation fullsend performs).

Also replace the ambiguous "service account" wording in the setup
overview, prerequisites and bot-filtering paragraph, and point the 401
troubleshooting row at the rotation section.

Atlassian service-account details come from Atlassian's documentation
as cited in the issue; the sandbox had no network access to re-check
them.

Note: pre-commit could not fetch remote hook repos (TLS failure in the
sandbox). The applicable hooks were run directly instead: whitespace,
EOF, line-ending and merge-marker checks, lint-docs-links,
lint-broken-symlinks, lychee --offline --include-fragments, and
gitleaks via scan-secrets. All passed.

Closes #4885

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team October 21, 2026 20:07
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Oct 21, 2026
@fullsend-ai-review

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

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:09 PM UTC · Completed 8:18 PM UTC

Commit: 3248300 · View workflow run →

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

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://01370ae9-site.fullsend-ai.workers.dev

Commit: 5822c659f94ab67a27ddce547f495e2cc4b30946

@codecov

codecov Bot commented Oct 21, 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 Oct 21, 2026
@fullsend-ai-review

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

Copy link
Copy Markdown

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

Details

Documentation-only update by a bot aligning with issue #4885, elevated to moderate risk by git history showing recent churn (8 commits in 30 days) and high change coupling.

Previous run

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

Details

Documentation-only update by a bot aligning with issue #4885, elevated to moderate risk by git history showing recent churn (8 commits in 30 days) and high change coupling.

Previous run (2)

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

Details

Documentation-only update by a bot aligning with issue #4885, elevated to moderate risk by git history showing recent churn (8 commits in 30 days) and high change coupling.

@fullsend-ai-review

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

Copy link
Copy Markdown

Looks good to me

Earlier findings

  • docs/guides/user/jira-integration.md:202, api-contract — resolved: both base64 credential examples now pipe through tr -d '\r\n', so the stored value is a single line.
Previous run

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

Review

Findings

Medium

  • [api-contract] docs/guides/user/jira-integration.md:202 — The rotation command produces a multiline credential on GNU/Linux: base64 wraps output at 76 characters by default, and an email plus Atlassian API token is well over 57 bytes. Piping that output straight into a secret store, as step 4 now recommends, stores embedded newlines instead of the single-line value HTTP Basic auth needs. That can break sandbox Jira access after rotation. The same unwrapped | base64 pattern is in the pre-existing text at line 77.
    Remediation: Generate a single-line credential, for example printf '%s' "${JIRA_USER_EMAIL}:${JIRA_TOKEN}" | base64 | tr -d '\r\n', before piping it into the secret store. Fix the line-77 example the same way.

Earlier findings

  • docs/guides/user/jira-integration.md:202, secret-exposure, resolved. Rotation step 4 now says the encoded value is a secret and warns against leaving it in terminal scrollback or logs. It also recommends piping it into the secret store's stdin input.

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
Previous run (2)

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6InNlY3JldC1leHBvc3VyZSIsImZpbGUiOiJkb2NzL2d1aWRlcy91c2VyL2ppcmEtaW50ZWdyYXRpb24ubWQiLCJpZCI6ImZfMTY1ZTFlYmQ4MzI0YmE0OSIsImxpbmUiOjIwMiwiYWN0aW9uYWJsZSI6dHJ1ZX1dfQ== -->

Review

Findings

Low

  • [secret-exposure] docs/guides/user/jira-integration.md:202 — Rotation step 4 tells users to run printf '%s' "${JIRA_USER_EMAIL}:${JIRA_TOKEN}" | base64. This prints the reusable Basic-auth credential to stdout, where it can stay in terminal scrollback or captured session logs. Base64 is only an encoding and offers no protection. The doc does not warn that the output is a secret.
    Remediation: Add a short note that the encoded value is a secret and should not be left in logs or scrollback. Where possible, pipe it straight into the store's secret-input mechanism instead of displaying it.

Labels: PR modifies user-facing documentation only


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-review fullsend-ai-review Bot added the component/docs User-facing documentation label Oct 21, 2026
@fullsend-ai-coder

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

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 8:20 PM UTC · Completed 8:23 PM UTC

Commit: 3248300 · View workflow run →

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

Warn in the token rotation steps that the base64-encoded credential is a
secret and should not be left in terminal scrollback or logs; recommend
piping it straight into the secret store's stdin input.

Note: pre-commit could not run (hook repositories not fetchable in the
sandbox). Checked trailing whitespace via git diff --check, ran the
secret scan, and ran lychee offline link check on the file.

Addresses #8678

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 the single low-severity review finding by adding a secret-handling warning to rotation step 4 of the Jira integration guide.

Fixed (1):

  1. Rotation step 4 prints the reusable base64 Basic-auth credential without warning that it is a secret (low, secret-exposure) (docs/guides/user/jira-integration.md): Added a note to step 4 that the encoded value is a secret, that base64 offers no protection, that it should not be left in scrollback or logs, and that it should be piped directly into the secret store's stdin input where possible.

Tests: passed

CI inspections (4):

  1. test (passing, success): Project test job passed.
  2. commit-lint (passing, success): Commit lint passed.
  3. build (passing, success): Site build passed.
  4. gateway-doc-configs (passing, success): Doc config check passed.

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 21, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:25 PM UTC · Completed 8:34 PM UTC

Commit: f60ce30 · View workflow run →

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

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

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

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 8:36 PM UTC · Completed 8:39 PM UTC

Commit: f60ce30 · View workflow run →

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

Strip line wraps from the base64-encoded Jira credential examples so the
stored value is a single line (GNU base64 wraps at 76 characters).

Note: pre-commit could not fetch remote hook repositories; ran the
applicable hooks directly (whitespace, docs link scope, markdown links,
broken symlinks), all passing. No tests apply to this docs-only change.

Addresses #8678

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

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 2 (bot-triggered)

Fixed the one open finding: both base64 credential examples now strip line wraps so the stored value is single-line. The earlier secret-exposure finding was already resolved.

Fixed (1):

  1. Base64 credential examples produce wrapped multiline output on GNU/Linux (rotation step and provider description) (docs/guides/user/jira-integration.md): Piped both base64 examples through tr -d '\r\n' and added a note explaining that GNU base64 wraps lines and Basic auth needs a single-line value.

Tests: passed

CI inspections (4):

  1. test (passing, success)
  2. build (passing, success)
  3. commit-lint (passing, success)
  4. codecov/patch (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 21, 2026 •

Copy link
Copy Markdown

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

Commit: 5822c65 · View workflow run →

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

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review October 21, 2026 20:48

Superseded by updated review

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 5822c659 Deployed Oct 21, 2026 by github-actions[bot]
dev — 5822c659 Deployed Oct 21, 2026 by fullsend-ai-coder[bot] via playback #17570
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.

Define Jira authentication strategy: interim service account credentials

0 participants