Repository navigation
docs(adr): add ADR 0156, separate the Jira API URL from the site URL - #9024
Conversation
Fullsend's Jira integration authenticates as one non-human identity, and Atlassian Cloud offers two kinds: a regular user account used as a bot (classic API token at the site URL, the only kind Fullsend supports today) and an Atlassian-managed service account (scoped token or OAuth 2.0, accepted only through the Atlassian API gateway). ADR 0156 explains both for readers new to them, weighs each, and decides that Fullsend supports both, chosen explicitly per deployment, with the bot-account path unchanged and remaining the default. Also annotates docs/architecture.md and the agent-infrastructure problem doc per the ADR process. Implementation is tracked in #9007. Related to #9007 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
Code Review by Qodo🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)
Great, no issues found!Qodo reviewed your code and found no material issues that require reviewTip of the day💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent |
PR Summary by QodoDocument support for bot and service accounts in Jira
AI Description
Diagram
High-Level Assessment
Files changed (3)
|
|
🤖 Finished Review · ✅ Success · Started 6:00 PM UTC · Completed 6:15 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $2.03 |
Site previewPreview: https://679b2e6c-site.fullsend-ai.workers.dev Commit: |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
<!-- fullsend:risk-assessment --> DetailsDocumentation-only PR adding ADR 0156 with no protected or CI paths, but scored moderate due to high churn and multi-author contention on docs/architecture.md. Previous run<!-- fullsend:risk-assessment --> DetailsDocumentation-only PR adding ADR 0156 with no protected or CI paths, but scored moderate due to high churn and multi-author contention on docs/architecture.md. Previous run (2)<!-- fullsend:risk-assessment --> DetailsDocumentation-only PR adding ADR 0156 with no protected or CI paths, but scored moderate due to high churn and multi-author contention on docs/architecture.md. |
|
Looks good to me Previous run<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJhcHByb3ZlIiwiZmluZGluZ3MiOltdfQ== --> Looks good to me Previous run (2)<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJhcHByb3ZlIiwiZmluZGluZ3MiOltdfQ== --> Looks good to me Labels: Docs-only PR adding an ADR |
…ot account A person's own Atlassian account authenticates exactly like a bot account, and Fullsend cannot tell them apart. Say so in ADR 0156, and say why it is still not a supported choice: the poller treats the authenticated account as itself, so that person's comments and label changes never dispatch (the Jira guide's dedicated-account section). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
|
🤖 Finished Review · ✅ Success · Started 6:44 PM UTC · Completed 6:59 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.63 |
Superseded by updated review
…n rule The ADR guidance that merged in #8972 keeps file and function evidence out of ADR bodies: describe current behaviour in plain language, link the issue that records it, and put the code evidence at a commit SHA in the pull request description. Rewrite ADR 0156's Context paragraph that way. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
ADR 0156 is claimed by #9024, and 0154 and 0155 by other open PRs. Rename the file, update its title and heading, and the references in ADR 0153's Status note and docs/architecture.md. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
… URL The decision changes from "support both account kinds, chosen explicitly per deployment" to "keep the site URL for links and cloud-ID discovery, send API calls to a separate API URL that defaults to the Atlassian gateway and can be overridden". The gateway accepts both a bot account's classic token and a service account's scoped token with the same email-plus-token credential, so Fullsend never needs to know which kind it holds. OAuth 2.0 client credentials are out of scope. The default host change for existing deployments lands unless a maintainer objects; setting the API URL to the site URL restores today's behaviour. Renames the ADR file to match the new title and updates architecture.md and the agent-infrastructure problem doc. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
waynesun09
left a comment
There was a problem hiding this comment.
The decision is sound: keep the site URL for links and cloud-ID discovery, send API calls through the gateway, and need no account-kind setting. Three corrections before merge, since the client shipped (via the #9035 contract) ahead of this ADR:
- Remove the site-URL escape hatch. A fallback would keep unscoped classic tokens on the site host, and the client always calls
{api_url}/ex/jira/{cloudId}/..., so the escape hatch would build a broken URL. State instead that upgrading requires a credential that works through the gateway, that pinned deployments keep their current version until they switch, and that a classic token working on the gateway is an accepted risk Atlassian doesn't promise. - The API URL setting is the gateway host (default
https://api.atlassian.com). The cloud ID is always discovered from the site URL, and the run stops if discovery fails, so drop "set the API URL explicitly". Only the resolved{api_url}/ex/jira/{cloudId}is passed to agent scripts (#9218). - Auth mode: an email means Basic (bot user); no email means Bearer (service account). That still needs no account-kind setting.
Please keep the text independent of the config key, saying "site URL" and "API URL" rather than tracker.jira.*, so it holds if connection settings are restructured later (see the connections discussion on #9091). Minor: Context could link the Jira guide for the account-kind detail, and the "#9007" consequence can go. A rebase is needed for the architecture.md conflict.
The client shipped through the tracker.jira contract (#9035) before this ADR merged. Describe what it does: the API URL is the gateway host and Fullsend always calls {API URL}/ex/jira/{cloudId}, the cloud ID is always discovered and a failed discovery stops the run, and an email selects Basic auth while no email selects Bearer. Drop the site-URL escape hatch, which would build a broken URL, and state the upgrade requirement and the accepted risk instead. Point the agent-run consequence at #9218 and drop the #9007 consequence. Keep Context as of 2026-11-02 apart from past tense and a link to the Jira guide. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
OAuth client credentials shipped in #9183 (for #9176) and use the same API URL, so record them in the decision instead of leaving them out of scope, and mention them in the architecture summary. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
A service account's token is sent as a Bearer token without an email, not alongside the account's email. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
|
Thanks for the review. Yes, good catches, I made these updates (main is merged in too, which resolves the conflict):
The text uses "site URL" and "API URL" with no config key names, Context links the Jira guide, and the #9007 consequence is gone. Two changes beyond your review: the Decision now covers OAuth 2.0 client credentials (#9176, shipped in #9183), since they go to the same API URL, and I fixed a Context sentence that said both kinds of token are sent with the account's email. Since the decision text changed, could you and @ifireball take another look? Bill Murdock, with assistance from Claude Code |
waynesun09
left a comment
There was a problem hiding this comment.
Thanks, the Decision now matches the shipped client and holds without naming config keys. Approving. Two small fixes, please:
- Options, "API URL defaulting to the gateway": "or to pin the site URL" contradicts the Decision (no site-URL setting). Please drop that phrase.
- Context: "authenticates as as itself" has a doubled "as".
On our side, #9219 (for #9218) currently leaves JIRA_API_URL empty when discovery fails, so agents fall back to the site URL. I'm changing it to fail closed, as the Decision says: a Jira-sourced run whose discovery fails, or whose connection settings are missing or invalid, stops with a clear error.
Drop "or to pin the site URL" from the gateway-default option, which contradicts the decision, and reword the doubled "as" in Context. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
|
Thanks for approving. Yes, I fixed both: "or to pin the site URL" is gone from the gateway-default option, and the Context sentence now reads "the poller treats the account it signs in with as itself". Failing closed in #9219 when discovery fails sounds right to me. Bill Murdock, with assistance from Claude Code |
The E2E Tests run for 10afa40 failed before any job started, and a startup failure cannot be retried. No file changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
|
🤖 Finished Review · ⏭️ Skipped (PR #9024 is already merged) · Started 8:53 PM UTC · Completed 8:53 PM UTC Commit: Effort: high |
|
Review skipped — this PR is already merged. The Posted by fullsend pre-review check |
Summary
Adds ADR 0156: Fullsend separates the Jira API URL from the Jira site URL. The site URL stays the one required setting and keeps its human-facing jobs (links to issues, discovery of the site's cloud ID). API calls go to a separate, optional API URL that defaults to the Atlassian Platform API Gateway address for the site (
https://api.atlassian.com/ex/jira/<cloudId>). The gateway accepts the credentials of both kinds of non-human identity, a regular bot account and an Atlassian-managed service account, so both work with the same email-plus-token settings and Fullsend never has to ask which kind it holds. The ADR explains both kinds for readers who have not met them and records the two alternatives considered (an explicit account-kind setting, and an API URL defaulting to the site URL).This is a change of host for existing bot-account deployments. Per the ADR it lands unless a maintainer objects here; the escape hatch is setting the API URL to the site URL, which restores today's behaviour exactly.
Related Issue
Related to #9007, which tracks the implementation (draft PR #9033). This PR is the decision record only, per the ADR process; no code changes.
Changes
docs/ADRs/0156-separate-jira-api-url-from-site-url.md: the ADR (Context with the two account kinds and today's behaviour verified at6f45fa15b, three Options, Decision, forge-neutral Forge scope, Consequences).docs/architecture.md: one "Decided:" bullet beside the existing Jira poll entries.docs/problems/agent-infrastructure.md: annotates the resource-access question with the ADR.Evidence for the Context claims (at
6f45fa15b)Per the ADR citation rule that merged in #8972, the code evidence lives here rather than in the ADR body.
LiveClient.apiURL(internal/forge/jira/client.goline 171) concatenates the base URL and/rest/api/3;setAuth(line 175) sendsAuthorization: Basic base64(email:token)when an email is set. The email and token are required bybuildJiraClientininternal/cli/poll.go(lines 385-395),newJiraTrackerClientFromEnvininternal/cli/jira_tracker.goand thetrackerJiracase ofnewTrackerClientininternal/cli/tracker_client.go.internal/tracker/jira_client.gobuilds browse links from it.internal/scaffold/fullsend-repo/profiles/fullsend-atlassian-cloud.yamlline 11 (*.atlassian.net) is the only host entry.apiURLconcatenation is why a gateway URL inJIRA_BASE_URLworks, the browse links above then point at the gateway, and the profile above does not allowapi.atlassian.com.Testing
pre-commit runon the three files passes (markdown links, docs link scope, whitespace);hack/lint-adr-frontmatter,lint-adr-numbersandlint-adr-statuspass.make lintitself does not run on my machine because.python-versionpins 3.14, which is not installed; the hooks were run under 3.12.Checklist
!for breaking changes)🤖 Generated with Claude Code