Skip to content

docs(adr): add ADR 0156, separate the Jira API URL from the site URL - #9024

Merged
jwm4 merged 10 commits into
mainfrom
jwm4/adr-0156-jira-identities
Nov 9, 2026
Merged

jwm4 merged 10 commits into
mainfrom
jwm4/adr-0156-jira-identities

Conversation

@jwm4

@jwm4 jwm4 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

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 at 6f45fa15b, 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.

  • "every API call" goes to the site URL: LiveClient.apiURL (internal/forge/jira/client.go line 171) concatenates the base URL and /rest/api/3; setAuth (line 175) sends Authorization: Basic base64(email:token) when an email is set. The email and token are required by buildJiraClient in internal/cli/poll.go (lines 385-395), newJiraTrackerClientFromEnv in internal/cli/jira_tracker.go and the trackerJira case of newTrackerClient in internal/cli/tracker_client.go.
  • "the links to issues that it writes for humans" come from the same base URL: internal/tracker/jira_client.go builds browse links from it.
  • "the sandbox egress rule for Jira": internal/scaffold/fullsend-repo/profiles/fullsend-atlassian-cloud.yaml line 11 (*.atlassian.net) is the only host entry.
  • "pointing the site URL setting at the gateway ... works for API calls but produces wrong links and leaves the sandbox without Jira access": the same apiURL concatenation is why a gateway URL in JIRA_BASE_URL works, the browse links above then point at the gateway, and the profile above does not allow api.atlassian.com.
  • "a classic bot token has been observed to work" at the gateway, and the site URL rejects a service-account token: the measured auth results per token kind and host are recorded on jira: use scoped tokens with service-account and bot auth #9007.

Testing

  • pre-commit run on the three files passes (markdown links, docs link scope, whitespace); hack/lint-adr-frontmatter, lint-adr-numbers and lint-adr-status pass. make lint itself does not run on my machine because .python-version pins 3.14, which is not installed; the hooks were run under 3.12.
  • Tests added/updated: not applicable, docs only.

Checklist

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

🤖 Generated with Claude Code

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>
@qodo-code-review

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Document support for bot and service accounts in Jira

📝 Documentation 🕐 10-20 Minutes

Grey Divider

AI Description

• Add ADR 0156, choosing explicit per-deployment Jira identity selection while retaining bot
 accounts as the default.
• Document service-account gateway requirements and the implementation work tracked in #9007.
• Link the decision from the architecture overview and agent-infrastructure problem statement.
Diagram

graph TD
  Config["Deployment settings"] --> Mode{"Identity mode"} --> Bot["Bot account"] --> Site["Jira site URL"]
  Mode --> Service["Service account"] --> Gateway["Atlassian gateway"]
  Service -. "Human links" .-> Site
Loading
High-Level Assessment

The ADR’s dual-mode decision preserves existing deployments while allowing organizations to use managed service accounts. It considers and rejects bot-only support, which excludes those organizations, and service-only support, which would break existing deployments. Keeping implementation in #9007 appropriately separates the decision record from code changes.

Files changed (3) +141 / -1

Documentation (3) +141 / -1
0156-support-bot-and-service-accounts-for-jira-access.mdRecord the Jira identity decision +134/-0

Record the Jira identity decision

• Adds an accepted ADR comparing bot accounts, managed service accounts, and support for both. It chooses explicit per-deployment selection with the existing bot path as default, identifies gateway and sandbox implications, and leaves implementation to #9007.

docs/ADRs/0156-support-bot-and-service-accounts-for-jira-access.md

architecture.mdReference the Jira identity decision in the architecture overview +6/-0

Reference the Jira identity decision in the architecture overview

• Adds a Jira architecture bullet summarizing both supported identity types, their endpoints, and the bot-account default, with a link to ADR 0156.

docs/architecture.md

agent-infrastructure.mdLink the identity decision from the resource-access question +1/-1

Link the identity decision from the resource-access question

• Annotates the agent-infrastructure resource-access question to mark supported Jira identity types as decided in ADR 0156 while leaving other resource-access questions open.

docs/problems/agent-infrastructure.md

@fullsend-ai-review

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

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:00 PM UTC · Completed 6:15 PM UTC

Commit: 06bef3d · View workflow run →

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

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://679b2e6c-site.fullsend-ai.workers.dev

Commit: ab7df3101d6a92f54ae6cac51872effa22277727

@codecov

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

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

Copy link
Copy Markdown

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

Details

Documentation-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 -->
Risk Assessment: moderate (2/5)

Details

Documentation-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 -->
Risk Assessment: moderate (2/5)

Details

Documentation-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.

@fullsend-ai-review

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

Copy link
Copy Markdown

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

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 type/adr component/docs User-facing documentation labels Nov 2, 2026
…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>
@fullsend-ai-review

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

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:44 PM UTC · Completed 6:59 PM UTC

Commit: e40339a · View workflow run →

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

@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 dismissed their stale review November 2, 2026 18:59

Superseded by updated review

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 Nov 2, 2026
…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>
jwm4 added a commit that referenced this pull request Nov 2, 2026
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 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. 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.
  2. 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).
  3. 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.

jwm4 and others added 3 commits November 9, 2026 11:41
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>
@jwm4

jwm4 commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Yes, good catches, I made these updates (main is merged in too, which resolves the conflict):

  1. I removed the site-URL escape hatch. The Decision now says every deployment talks to the gateway, upgrading needs a credential that works there, a pinned deployment keeps its current behaviour until it switches, and a classic token working on the gateway is an accepted risk that Atlassian doesn't promise.
  2. The API URL is now the gateway host (default https://api.atlassian.com), and Fullsend always calls {API URL}/ex/jira/{cloudId}/.... The cloud ID is always discovered and a failed discovery stops the run, so "set the API URL explicitly" is gone. Only the resolved address is handed to agent scripts, with a consequence pointing at Set JIRA_API_URL and JIRA_BASE_URL for Jira-sourced agent runs #9218.
  3. An email selects Basic auth (bot account) and no email selects Bearer (service account), still with no account-kind setting.

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 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@jwm4

jwm4 commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

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

@jwm4
jwm4 enabled auto-merge November 9, 2026 18:17
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>
@jwm4
jwm4 added this pull request to the merge queue Nov 9, 2026
Merged via the queue into main with commit acce595 Nov 9, 2026
21 of 22 checks passed
@jwm4
jwm4 deleted the jwm4/adr-0156-jira-identities branch November 9, 2026 20:52
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ⏭️ Skipped (PR #9024 is already merged) · Started 8:53 PM UTC · Completed 8:53 PM UTC

Commit: e1461ff · View workflow run →

Effort: high

@fullsend-ai-review

Copy link
Copy Markdown

Review skipped — this PR is already merged.

The /fs-review command only reviews open PRs/MRs.

Posted by fullsend pre-review check

This branch was successfully deployed

1 active (outdated) and 1 inactive deployments
dev — e1461ffe Deployed Nov 9, 2026 by jwm4 via behaviour #19394
site-preview — ab7df310 Deployed Nov 9, 2026 by github-actions[bot]
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 risk/moderate PR risk: moderate type/adr

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants