From 875503565246b41285adf44ced7b3787f413b38c Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Thu, 9 Jul 2026 12:55:20 +0530 Subject: [PATCH 01/11] =?UTF-8?q?docs(adr):=20ADR=200069=20=E2=80=94=20Jir?= =?UTF-8?q?a=20project=20enrollment=20via=20fullsend=20CLI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> --- .../0069-jira-project-enrollment-via-cli.md | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/ADRs/0069-jira-project-enrollment-via-cli.md diff --git a/docs/ADRs/0069-jira-project-enrollment-via-cli.md b/docs/ADRs/0069-jira-project-enrollment-via-cli.md new file mode 100644 index 0000000000..4ab8af45f1 --- /dev/null +++ b/docs/ADRs/0069-jira-project-enrollment-via-cli.md @@ -0,0 +1,100 @@ +--- +title: "69. Jira project enrollment via fullsend CLI" +status: Accepted +relates_to: + - agent-infrastructure +topics: + - jira + - enrollment + - external-issue-trackers + - credentials +--- + +# 69. Jira project enrollment via fullsend CLI + +Date: 2026-07-09 + +## Status + +Accepted + +## Context + +Fullsend's dispatch model assumes events originate from GitHub — issues, +PRs, and comments flow through the shim workflow +([ADR 0034](0034-centralized-shim-routing-via-dispatch.md)) into agent +pipelines. Enterprise teams commonly use Jira Enterprise/Cloud for backlog management, +so Jira issues need an entry path into the same pipeline. + +A working proof-of-concept ([manish-jira](https://github.com/rh-hemartin-fullsendai/manish-jira)) +validated the approach: Jira Automation rules fire webhooks to GitHub's +`repository_dispatch` API, a dispatch workflow validates enrollment and +routes to agent workflows, and agents use the customization layer +(`.fullsend/customized/`) to handle Jira-specific event formats. Jira +credentials stay on the GitHub Actions host and never enter the agent +sandbox, following the prefetch model from +[ADR 0017](0017-credential-isolation-for-sandboxed-agents.md). + +Today this setup is entirely manual. The enrollment CLI automates it. + +Repo-to-issue association (which code repository handles which Jira issue) +is a separate concern handled by the poll driver design and is out of scope +for this ADR. + +## Options + +### Alternative: Jira Connect or Forge app + +A Jira Connect or Forge app could receive webhooks natively without +`repository_dispatch` as a bridge. Rejected because it requires hosting an +external service, an app distribution and consent flow, and a fundamentally +larger product scope. The CLI-only approach delivers value without +operational infrastructure. + +### Alternative: Polling via scheduled workflows + +A GitHub Actions schedule could poll Jira for new issues using JQL. +Rejected for the enrollment path — polling adds latency and complexity. +However, the poll driver design may use this pattern for repo association, +which is a separate concern. + +## Decision + +Add a `fullsend jira enroll ` CLI command that configures +the inbound event path (Jira Automation → GitHub `repository_dispatch`) +and the outbound credential path (Jira API token as GitHub secret) for a +single Jira project. + +The command creates or updates a `.jira.yml` enrollment config (project +key, host), attempts to create Jira Automation rules via the +[Automation Rule Management API](https://developer.atlassian.com/cloud/automation/rest/api-group-rule-management/), +commits dispatch and agent workflow files, and sets Jira credential +secrets on the repo. Enrollment is idempotent. + +The Automation API currently requires site admin for write operations +([AUTO-2120](https://jira.atlassian.com/browse/AUTO-2120)). When the API +returns 403, the CLI prints pre-filled manual instructions for creating +the rules in the Jira UI. + +No new agents are introduced. Existing agents gain Jira awareness through +the customization layer — Jira-specific pre/post scripts and agent prompt +sections are the repo admin's responsibility, not part of enrollment. + +The CLI follows the `fullsend github` command pattern: cobra subcommands, +credential resolution cascade (flag → env → prompt), and `--dry-run` +support. + +## Consequences + +- External issue trackers can connect to fullsend without modifying agents + or the core dispatch model. +- Jira API tokens follow the prefetch credential isolation model + ([ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)) — stored + as GitHub secrets, consumed by host-side scripts, never in the sandbox. +- The AUTO-2120 limitation means non-admin users must create automation + rules manually; if Atlassian resolves it, the manual fallback path + becomes unused but harmless. +- Jira API token rotation is the repo admin's responsibility — re-running + `fullsend jira enroll` with a new token updates the secret. +- Repo association is intentionally out of scope — the poll driver design + addresses which issues route to which code repositories. From 48b783facdbdfbe694ec11c9bcc7888419a3b692 Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Thu, 9 Jul 2026 14:25:27 +0530 Subject: [PATCH 02/11] docs(adr): address review feedback for ADR 0069 - Add architecture.md entry for Jira enrollment under dispatch section - Replace .fullsend/customized/ references with harness composition (ADR 0045) to align with ADR 0064 deprecation of customized overlay Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> --- docs/ADRs/0069-jira-project-enrollment-via-cli.md | 11 +++++++---- docs/architecture.md | 1 + 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/ADRs/0069-jira-project-enrollment-via-cli.md b/docs/ADRs/0069-jira-project-enrollment-via-cli.md index 4ab8af45f1..e31b68fd17 100644 --- a/docs/ADRs/0069-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0069-jira-project-enrollment-via-cli.md @@ -29,8 +29,10 @@ so Jira issues need an entry path into the same pipeline. A working proof-of-concept ([manish-jira](https://github.com/rh-hemartin-fullsendai/manish-jira)) validated the approach: Jira Automation rules fire webhooks to GitHub's `repository_dispatch` API, a dispatch workflow validates enrollment and -routes to agent workflows, and agents use the customization layer -(`.fullsend/customized/`) to handle Jira-specific event formats. Jira +routes to agent workflows, and agents use harness composition +([ADR 0045](0045-forge-portable-harness-schema.md)) to handle +Jira-specific event formats via `base:`, `pre_script`, and `forge:` +overrides. Jira credentials stay on the GitHub Actions host and never enter the agent sandbox, following the prefetch model from [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md). @@ -77,8 +79,9 @@ returns 403, the CLI prints pre-filled manual instructions for creating the rules in the Jira UI. No new agents are introduced. Existing agents gain Jira awareness through -the customization layer — Jira-specific pre/post scripts and agent prompt -sections are the repo admin's responsibility, not part of enrollment. +harness composition ([ADR 0045](0045-forge-portable-harness-schema.md)) — +Jira-specific pre/post scripts and `forge:` overrides are the repo +admin's responsibility, not part of enrollment. The CLI follows the `fullsend github` command pattern: cobra subcommands, credential resolution cascade (flag → env → prompt), and `--dry-run` diff --git a/docs/architecture.md b/docs/architecture.md index e0deddd5a6..4763267201 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,6 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). +- Jira project enrollment: `fullsend jira enroll` CLI command configures inbound event path (Jira Automation → `repository_dispatch`) and outbound credentials (Jira API token as GitHub secret). Existing agents gain Jira awareness via harness composition, not new agents. Repo-to-issue association is handled separately by the poll driver design ([ADR 0069](ADRs/0069-jira-project-enrollment-via-cli.md)). **Open questions:** From 94bf25ca5557b61fff9b1bbc33d2ce019b6f1f42 Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Thu, 9 Jul 2026 14:46:59 +0530 Subject: [PATCH 03/11] docs(adr): condense ADR 0069 context to 3 paragraphs Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> --- docs/ADRs/0069-jira-project-enrollment-via-cli.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/ADRs/0069-jira-project-enrollment-via-cli.md b/docs/ADRs/0069-jira-project-enrollment-via-cli.md index e31b68fd17..83c4052950 100644 --- a/docs/ADRs/0069-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0069-jira-project-enrollment-via-cli.md @@ -36,8 +36,7 @@ overrides. Jira credentials stay on the GitHub Actions host and never enter the agent sandbox, following the prefetch model from [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md). - -Today this setup is entirely manual. The enrollment CLI automates it. +Today this setup is entirely manual; the enrollment CLI automates it. Repo-to-issue association (which code repository handles which Jira issue) is a separate concern handled by the poll driver design and is out of scope From 1617b635eb74adc6347da6385ead91817c595f0a Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Thu, 9 Jul 2026 15:24:43 +0530 Subject: [PATCH 04/11] docs(adr): add problem-doc link and clarify scope in ADR 0069 - Link to agent-infrastructure problem doc in Context for traceability - Rephrase agent scope boundary as a scope clarification, not a separate decision Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> --- .../0069-jira-project-enrollment-via-cli.md | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/ADRs/0069-jira-project-enrollment-via-cli.md b/docs/ADRs/0069-jira-project-enrollment-via-cli.md index 83c4052950..e7f56d908f 100644 --- a/docs/ADRs/0069-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0069-jira-project-enrollment-via-cli.md @@ -20,11 +20,12 @@ Accepted ## Context -Fullsend's dispatch model assumes events originate from GitHub — issues, -PRs, and comments flow through the shim workflow +Fullsend's dispatch model (see [agent-infrastructure](../problems/agent-infrastructure.md)) +assumes events originate from GitHub — issues, PRs, and comments flow +through the shim workflow ([ADR 0034](0034-centralized-shim-routing-via-dispatch.md)) into agent -pipelines. Enterprise teams commonly use Jira Enterprise/Cloud for backlog management, -so Jira issues need an entry path into the same pipeline. +pipelines. Enterprise teams commonly use Jira Enterprise/Cloud for backlog +management, so Jira issues need an entry path into the same pipeline. A working proof-of-concept ([manish-jira](https://github.com/rh-hemartin-fullsendai/manish-jira)) validated the approach: Jira Automation rules fire webhooks to GitHub's @@ -77,14 +78,12 @@ The Automation API currently requires site admin for write operations returns 403, the CLI prints pre-filled manual instructions for creating the rules in the Jira UI. -No new agents are introduced. Existing agents gain Jira awareness through -harness composition ([ADR 0045](0045-forge-portable-harness-schema.md)) — -Jira-specific pre/post scripts and `forge:` overrides are the repo -admin's responsibility, not part of enrollment. - -The CLI follows the `fullsend github` command pattern: cobra subcommands, -credential resolution cascade (flag → env → prompt), and `--dry-run` -support. +The enrollment scope is the event bridge and credentials only — agent-level +Jira awareness (pre/post scripts, `forge:` overrides via +[ADR 0045](0045-forge-portable-harness-schema.md)) is the repo admin's +responsibility. The CLI follows the `fullsend github` command pattern: +cobra subcommands, credential resolution cascade (flag → env → prompt), +and `--dry-run` support. ## Consequences From 755080b53a2badea9620331b6ead6aa24d6ab824 Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Fri, 10 Jul 2026 10:08:22 +0530 Subject: [PATCH 05/11] docs(adr): add ADR 0063 cross-references and fix options headings - Link "poll driver design" to ADR 0063 in Context, Options, and Consequences sections - Add ADR 0063 link in architecture.md Jira enrollment entry - Rename Options headings from "Alternative:" to "Option N:" per project convention Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> --- docs/ADRs/0069-jira-project-enrollment-via-cli.md | 15 +++++++++------ docs/architecture.md | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/ADRs/0069-jira-project-enrollment-via-cli.md b/docs/ADRs/0069-jira-project-enrollment-via-cli.md index e7f56d908f..c2fc9dd6fe 100644 --- a/docs/ADRs/0069-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0069-jira-project-enrollment-via-cli.md @@ -40,12 +40,13 @@ sandbox, following the prefetch model from Today this setup is entirely manual; the enrollment CLI automates it. Repo-to-issue association (which code repository handles which Jira issue) -is a separate concern handled by the poll driver design and is out of scope +is a separate concern handled by the poll driver design +([ADR 0063](0063-polling-based-work-discovery.md)) and is out of scope for this ADR. ## Options -### Alternative: Jira Connect or Forge app +### Option 1: Jira Connect or Forge app A Jira Connect or Forge app could receive webhooks natively without `repository_dispatch` as a bridge. Rejected because it requires hosting an @@ -53,12 +54,13 @@ external service, an app distribution and consent flow, and a fundamentally larger product scope. The CLI-only approach delivers value without operational infrastructure. -### Alternative: Polling via scheduled workflows +### Option 2: Polling via scheduled workflows A GitHub Actions schedule could poll Jira for new issues using JQL. Rejected for the enrollment path — polling adds latency and complexity. -However, the poll driver design may use this pattern for repo association, -which is a separate concern. +However, the poll driver design +([ADR 0063](0063-polling-based-work-discovery.md)) may use this pattern +for repo association, which is a separate concern. ## Decision @@ -98,4 +100,5 @@ and `--dry-run` support. - Jira API token rotation is the repo admin's responsibility — re-running `fullsend jira enroll` with a new token updates the secret. - Repo association is intentionally out of scope — the poll driver design - addresses which issues route to which code repositories. + ([ADR 0063](0063-polling-based-work-discovery.md)) addresses which + issues route to which code repositories. diff --git a/docs/architecture.md b/docs/architecture.md index 4763267201..dd5ca18f8b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,7 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -- Jira project enrollment: `fullsend jira enroll` CLI command configures inbound event path (Jira Automation → `repository_dispatch`) and outbound credentials (Jira API token as GitHub secret). Existing agents gain Jira awareness via harness composition, not new agents. Repo-to-issue association is handled separately by the poll driver design ([ADR 0069](ADRs/0069-jira-project-enrollment-via-cli.md)). +- Jira project enrollment: `fullsend jira enroll` CLI command configures inbound event path (Jira Automation → `repository_dispatch`) and outbound credentials (Jira API token as GitHub secret). Existing agents gain Jira awareness via harness composition, not new agents. Repo-to-issue association is handled separately by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md), [ADR 0069](ADRs/0069-jira-project-enrollment-via-cli.md)). **Open questions:** From bac62e058f56f080938459079255e8089687e8fd Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Mon, 13 Jul 2026 09:57:15 +0530 Subject: [PATCH 06/11] docs(adr): move Jira config from .jira.yml to .fullsend/config.yaml Replace standalone .jira.yml with integrations.jira key in .fullsend/config.yaml per reviewer feedback. Org-level config interaction is out of scope. Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> --- docs/ADRs/0069-jira-project-enrollment-via-cli.md | 5 +++-- docs/architecture.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/ADRs/0069-jira-project-enrollment-via-cli.md b/docs/ADRs/0069-jira-project-enrollment-via-cli.md index c2fc9dd6fe..2a660071e5 100644 --- a/docs/ADRs/0069-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0069-jira-project-enrollment-via-cli.md @@ -69,8 +69,9 @@ the inbound event path (Jira Automation → GitHub `repository_dispatch`) and the outbound credential path (Jira API token as GitHub secret) for a single Jira project. -The command creates or updates a `.jira.yml` enrollment config (project -key, host), attempts to create Jira Automation rules via the +The command adds Jira project entries to the `integrations.jira` key in +`.fullsend/config.yaml` (project key, host), attempts to create Jira +Automation rules via the [Automation Rule Management API](https://developer.atlassian.com/cloud/automation/rest/api-group-rule-management/), commits dispatch and agent workflow files, and sets Jira credential secrets on the repo. Enrollment is idempotent. diff --git a/docs/architecture.md b/docs/architecture.md index dd5ca18f8b..52faeae98d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,7 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -- Jira project enrollment: `fullsend jira enroll` CLI command configures inbound event path (Jira Automation → `repository_dispatch`) and outbound credentials (Jira API token as GitHub secret). Existing agents gain Jira awareness via harness composition, not new agents. Repo-to-issue association is handled separately by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md), [ADR 0069](ADRs/0069-jira-project-enrollment-via-cli.md)). +- Jira project enrollment: `fullsend jira enroll` CLI command configures inbound event path (Jira Automation → `repository_dispatch`) and outbound credentials (Jira API token as GitHub secret). Enrollment config lives in `.fullsend/config.yaml` under `integrations.jira`. Existing agents gain Jira awareness via harness composition, not new agents. Repo-to-issue association is handled separately by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md), [ADR 0069](ADRs/0069-jira-project-enrollment-via-cli.md)). **Open questions:** From d011f220aff1c4247ad37b857b044cb4c28d261e Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Thu, 30 Jul 2026 12:28:30 +0530 Subject: [PATCH 07/11] =?UTF-8?q?docs(adr):=20rescope=20and=20renumber=20A?= =?UTF-8?q?DR=200069=20=E2=86=92=200071?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rescope Jira project enrollment ADR to focus solely on credential provisioning and config metadata via `fullsend jira enroll`. Removes conflicting push-based dispatch design (ADR 0063 owns polling). Renumber from 0069 to 0071 to avoid collision with ADR 0069 (ready-made configuration presets) on main. Signed-off-by: Manish Kumar Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Co-authored-by: Cursor --- .../0069-jira-project-enrollment-via-cli.md | 105 ------------------ .../0071-jira-project-enrollment-via-cli.md | 89 +++++++++++++++ docs/architecture.md | 2 +- 3 files changed, 90 insertions(+), 106 deletions(-) delete mode 100644 docs/ADRs/0069-jira-project-enrollment-via-cli.md create mode 100644 docs/ADRs/0071-jira-project-enrollment-via-cli.md diff --git a/docs/ADRs/0069-jira-project-enrollment-via-cli.md b/docs/ADRs/0069-jira-project-enrollment-via-cli.md deleted file mode 100644 index 2a660071e5..0000000000 --- a/docs/ADRs/0069-jira-project-enrollment-via-cli.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "69. Jira project enrollment via fullsend CLI" -status: Accepted -relates_to: - - agent-infrastructure -topics: - - jira - - enrollment - - external-issue-trackers - - credentials ---- - -# 69. Jira project enrollment via fullsend CLI - -Date: 2026-07-09 - -## Status - -Accepted - -## Context - -Fullsend's dispatch model (see [agent-infrastructure](../problems/agent-infrastructure.md)) -assumes events originate from GitHub — issues, PRs, and comments flow -through the shim workflow -([ADR 0034](0034-centralized-shim-routing-via-dispatch.md)) into agent -pipelines. Enterprise teams commonly use Jira Enterprise/Cloud for backlog -management, so Jira issues need an entry path into the same pipeline. - -A working proof-of-concept ([manish-jira](https://github.com/rh-hemartin-fullsendai/manish-jira)) -validated the approach: Jira Automation rules fire webhooks to GitHub's -`repository_dispatch` API, a dispatch workflow validates enrollment and -routes to agent workflows, and agents use harness composition -([ADR 0045](0045-forge-portable-harness-schema.md)) to handle -Jira-specific event formats via `base:`, `pre_script`, and `forge:` -overrides. Jira -credentials stay on the GitHub Actions host and never enter the agent -sandbox, following the prefetch model from -[ADR 0017](0017-credential-isolation-for-sandboxed-agents.md). -Today this setup is entirely manual; the enrollment CLI automates it. - -Repo-to-issue association (which code repository handles which Jira issue) -is a separate concern handled by the poll driver design -([ADR 0063](0063-polling-based-work-discovery.md)) and is out of scope -for this ADR. - -## Options - -### Option 1: Jira Connect or Forge app - -A Jira Connect or Forge app could receive webhooks natively without -`repository_dispatch` as a bridge. Rejected because it requires hosting an -external service, an app distribution and consent flow, and a fundamentally -larger product scope. The CLI-only approach delivers value without -operational infrastructure. - -### Option 2: Polling via scheduled workflows - -A GitHub Actions schedule could poll Jira for new issues using JQL. -Rejected for the enrollment path — polling adds latency and complexity. -However, the poll driver design -([ADR 0063](0063-polling-based-work-discovery.md)) may use this pattern -for repo association, which is a separate concern. - -## Decision - -Add a `fullsend jira enroll ` CLI command that configures -the inbound event path (Jira Automation → GitHub `repository_dispatch`) -and the outbound credential path (Jira API token as GitHub secret) for a -single Jira project. - -The command adds Jira project entries to the `integrations.jira` key in -`.fullsend/config.yaml` (project key, host), attempts to create Jira -Automation rules via the -[Automation Rule Management API](https://developer.atlassian.com/cloud/automation/rest/api-group-rule-management/), -commits dispatch and agent workflow files, and sets Jira credential -secrets on the repo. Enrollment is idempotent. - -The Automation API currently requires site admin for write operations -([AUTO-2120](https://jira.atlassian.com/browse/AUTO-2120)). When the API -returns 403, the CLI prints pre-filled manual instructions for creating -the rules in the Jira UI. - -The enrollment scope is the event bridge and credentials only — agent-level -Jira awareness (pre/post scripts, `forge:` overrides via -[ADR 0045](0045-forge-portable-harness-schema.md)) is the repo admin's -responsibility. The CLI follows the `fullsend github` command pattern: -cobra subcommands, credential resolution cascade (flag → env → prompt), -and `--dry-run` support. - -## Consequences - -- External issue trackers can connect to fullsend without modifying agents - or the core dispatch model. -- Jira API tokens follow the prefetch credential isolation model - ([ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)) — stored - as GitHub secrets, consumed by host-side scripts, never in the sandbox. -- The AUTO-2120 limitation means non-admin users must create automation - rules manually; if Atlassian resolves it, the manual fallback path - becomes unused but harmless. -- Jira API token rotation is the repo admin's responsibility — re-running - `fullsend jira enroll` with a new token updates the secret. -- Repo association is intentionally out of scope — the poll driver design - ([ADR 0063](0063-polling-based-work-discovery.md)) addresses which - issues route to which code repositories. diff --git a/docs/ADRs/0071-jira-project-enrollment-via-cli.md b/docs/ADRs/0071-jira-project-enrollment-via-cli.md new file mode 100644 index 0000000000..9588607db8 --- /dev/null +++ b/docs/ADRs/0071-jira-project-enrollment-via-cli.md @@ -0,0 +1,89 @@ +--- +title: "71. Jira project enrollment via fullsend CLI" +status: Accepted +relates_to: + - agent-infrastructure +topics: + - jira + - enrollment + - external-issue-trackers + - credentials +--- + +# 71. Jira project enrollment via fullsend CLI + +Date: 2026-07-09 + +## Status + +Accepted + +## Context + +Fullsend's dispatch model (see [agent-infrastructure](../problems/agent-infrastructure.md)) +uses pluggable input drivers to normalize events from multiple sources +([ADR 0061](0061-harness-cel-dispatch.md)). For Jira, the poll driver +([ADR 0063](0063-polling-based-work-discovery.md)) discovers work items +via JQL and dispatches agents through the shared pipeline. ADR 0063 +defers credential placement as an open question — Jira API tokens need +to reach the poll driver and agent pre-scripts, but no ADR specifies +how those credentials are provisioned or where enrollment metadata lives. + +A proof-of-concept ([manish-jira](https://github.com/rh-hemartin-fullsendai/manish-jira)) +validated end-to-end Jira-to-agent dispatch. The enrollment steps +(credential provisioning, config updates) were entirely manual; the +CLI automates them. + +## Options + +### Option 1: Manual credential setup per documentation + +Operators follow a guide to create forge secrets and edit +`.fullsend/config.yaml` by hand. Rejected — error-prone for multi-project +setups and inconsistent across forges. + +### Option 2: `fullsend jira enroll` CLI command + +A CLI command provisions credentials and writes enrollment metadata. +Follows established CLI patterns (cobra subcommands, `--dry-run`). + +## Decision + +Add a `fullsend jira enroll ` CLI command that provisions +Jira API credentials as forge secrets and writes enrollment metadata to +`.fullsend/config.yaml`. The command resolves Jira credentials via +environment variables or CLI flags and supports `--dry-run`. + +Enrollment writes Jira project entries to the `integrations.jira` key +in `.fullsend/config.yaml` (project key, host URL). Poll driver +configuration in `poll.input_drivers[].connection` references this +metadata. Credentials are stored as forge-level secrets (not checked +into the repository), compatible with +[ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)'s +credential isolation model. Ensuring credentials stay outside the agent +sandbox is the harness author's responsibility (via `runner_env` and +pre/post scripts). + +Enrollment is idempotent — re-running with a new token rotates the +secret. The enrollment scope is credentials and config only; the dispatch +mechanism is the poll driver's responsibility +([ADR 0063](0063-polling-based-work-discovery.md)), and agent-level +Jira awareness (harness `pre_script`, `forge:` overrides via +[ADR 0045](0045-forge-portable-harness-schema.md)) is the repo admin's +responsibility. + +## Consequences + +- Jira credential provisioning is automated and consistent across forges. +- Credentials are stored as forge secrets, compatible with + [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)'s + isolation model. Sandbox isolation is enforced downstream by harness + configuration (`runner_env`, pre/post scripts), not by enrollment. +- ADR 0063's open question on credential placement is resolved for the + enrollment path; poll drivers read connection metadata from + `integrations.jira`. +- Jira API token rotation is the repo admin's responsibility — re-running + `fullsend jira enroll` with a new token updates the secret. +- Repo-to-issue association is out of scope — the poll driver + ([ADR 0063](0063-polling-based-work-discovery.md)) handles which + issues route to which repositories. diff --git a/docs/architecture.md b/docs/architecture.md index 52faeae98d..609dc7d5bf 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,7 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -- Jira project enrollment: `fullsend jira enroll` CLI command configures inbound event path (Jira Automation → `repository_dispatch`) and outbound credentials (Jira API token as GitHub secret). Enrollment config lives in `.fullsend/config.yaml` under `integrations.jira`. Existing agents gain Jira awareness via harness composition, not new agents. Repo-to-issue association is handled separately by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md), [ADR 0069](ADRs/0069-jira-project-enrollment-via-cli.md)). +- Jira project enrollment: `fullsend jira enroll` CLI command provisions Jira API credentials as forge secrets and writes enrollment metadata to `.fullsend/config.yaml` under `integrations.jira` ([ADR 0071](ADRs/0071-jira-project-enrollment-via-cli.md)). Poll drivers ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)) reference this metadata for connection config; repo-to-issue association is handled by the poll driver design. **Open questions:** From fee93d2460b496b71c288e48f199736b5df08adf Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Fri, 31 Jul 2026 11:41:55 +0530 Subject: [PATCH 08/11] =?UTF-8?q?docs(adr):=20renumber=20ADR=200071=20?= =?UTF-8?q?=E2=86=92=200079=20and=20fix=20review=20feedback?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Renumber to 0079 to avoid collision with PR #2791 (ADR 0071 auto-merge) and PR #5016 (ADR 0072 pre-script output protocol) - Replace deprecated runner_env with env.runner/env.sandbox per ADR 0055 - Remove incorrect ADR 0045 forge: citation for Jira-aware behavior - Narrow Consequences claim to Jira-token portion of ADR 0063's open question - Soften idempotent assertion to intended contract - Add missing ADR 0063 cross-reference in architecture.md Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Co-authored-by: Cursor --- ...> 0079-jira-project-enrollment-via-cli.md} | 33 +++++++++++-------- docs/architecture.md | 2 +- 2 files changed, 20 insertions(+), 15 deletions(-) rename docs/ADRs/{0071-jira-project-enrollment-via-cli.md => 0079-jira-project-enrollment-via-cli.md} (72%) diff --git a/docs/ADRs/0071-jira-project-enrollment-via-cli.md b/docs/ADRs/0079-jira-project-enrollment-via-cli.md similarity index 72% rename from docs/ADRs/0071-jira-project-enrollment-via-cli.md rename to docs/ADRs/0079-jira-project-enrollment-via-cli.md index 9588607db8..48d8bac256 100644 --- a/docs/ADRs/0071-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0079-jira-project-enrollment-via-cli.md @@ -1,5 +1,5 @@ --- -title: "71. Jira project enrollment via fullsend CLI" +title: "79. Jira project enrollment via fullsend CLI" status: Accepted relates_to: - agent-infrastructure @@ -10,7 +10,7 @@ topics: - credentials --- -# 71. Jira project enrollment via fullsend CLI +# 79. Jira project enrollment via fullsend CLI Date: 2026-07-09 @@ -61,16 +61,16 @@ metadata. Credentials are stored as forge-level secrets (not checked into the repository), compatible with [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)'s credential isolation model. Ensuring credentials stay outside the agent -sandbox is the harness author's responsibility (via `runner_env` and +sandbox is the harness author's responsibility (via `env.runner` / +`env.sandbox` per [ADR 0055](0055-unified-env-var-delivery.md) and pre/post scripts). -Enrollment is idempotent — re-running with a new token rotates the -secret. The enrollment scope is credentials and config only; the dispatch +Enrollment is designed to be idempotent — re-running with a new token +updates the forge secret. The enrollment scope is credentials and config only; the dispatch mechanism is the poll driver's responsibility ([ADR 0063](0063-polling-based-work-discovery.md)), and agent-level -Jira awareness (harness `pre_script`, `forge:` overrides via -[ADR 0045](0045-forge-portable-harness-schema.md)) is the repo admin's -responsibility. +Jira awareness (harness `pre_script` / `post_script`) is the repo +admin's responsibility. ## Consequences @@ -78,12 +78,17 @@ responsibility. - Credentials are stored as forge secrets, compatible with [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)'s isolation model. Sandbox isolation is enforced downstream by harness - configuration (`runner_env`, pre/post scripts), not by enrollment. -- ADR 0063's open question on credential placement is resolved for the - enrollment path; poll drivers read connection metadata from - `integrations.jira`. -- Jira API token rotation is the repo admin's responsibility — re-running - `fullsend jira enroll` with a new token updates the secret. + configuration (`env.runner` / `env.sandbox` per + [ADR 0055](0055-unified-env-var-delivery.md), pre/post scripts), not + by enrollment. +- The Jira-token portion of ADR 0063's open question on credential + placement is resolved for the enrollment path; poll drivers read + connection metadata from `integrations.jira`. Forge-native credentials + (`GITHUB_TOKEN`, App creds) remain unaddressed by this ADR. +- Jira API token rotation is the repo admin's responsibility — + re-running `fullsend jira enroll` with a new token is designed to + update the forge secret. Per-forge idempotency verification is tracked + as an implementation concern. - Repo-to-issue association is out of scope — the poll driver ([ADR 0063](0063-polling-based-work-discovery.md)) handles which issues route to which repositories. diff --git a/docs/architecture.md b/docs/architecture.md index 609dc7d5bf..63c392e593 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,7 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -- Jira project enrollment: `fullsend jira enroll` CLI command provisions Jira API credentials as forge secrets and writes enrollment metadata to `.fullsend/config.yaml` under `integrations.jira` ([ADR 0071](ADRs/0071-jira-project-enrollment-via-cli.md)). Poll drivers ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)) reference this metadata for connection config; repo-to-issue association is handled by the poll driver design. +- Jira project enrollment: `fullsend jira enroll` CLI command provisions Jira API credentials as forge secrets and writes enrollment metadata to `.fullsend/config.yaml` under `integrations.jira` ([ADR 0079](ADRs/0079-jira-project-enrollment-via-cli.md)). Poll drivers ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)) reference this metadata for connection config; repo-to-issue association is handled by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). **Open questions:** From 020a88a75bf0b70143a912f1aece158a5a5b06a1 Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Fri, 31 Jul 2026 12:47:23 +0530 Subject: [PATCH 09/11] docs(adr): replace integrations.jira with poll driver connection config Drop the standalone integrations.jira config key. Enrollment now writes Jira connection metadata directly into poll.input_drivers[].connection, consistent with ADR 0063's existing schema. A separate integration-level config key can be introduced by a future ADR if a push-based dispatch path (e.g. Jira Automation webhooks) is adopted. Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Co-authored-by: Cursor --- .../0079-jira-project-enrollment-via-cli.md | 31 +++++++++++-------- docs/architecture.md | 2 +- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/ADRs/0079-jira-project-enrollment-via-cli.md b/docs/ADRs/0079-jira-project-enrollment-via-cli.md index 48d8bac256..c1d28d8cde 100644 --- a/docs/ADRs/0079-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0079-jira-project-enrollment-via-cli.md @@ -44,20 +44,21 @@ setups and inconsistent across forges. ### Option 2: `fullsend jira enroll` CLI command -A CLI command provisions credentials and writes enrollment metadata. -Follows established CLI patterns (cobra subcommands, `--dry-run`). +A CLI command provisions credentials and writes poll driver connection +config. Follows established CLI patterns (cobra subcommands, `--dry-run`). ## Decision Add a `fullsend jira enroll ` CLI command that provisions -Jira API credentials as forge secrets and writes enrollment metadata to -`.fullsend/config.yaml`. The command resolves Jira credentials via -environment variables or CLI flags and supports `--dry-run`. - -Enrollment writes Jira project entries to the `integrations.jira` key -in `.fullsend/config.yaml` (project key, host URL). Poll driver -configuration in `poll.input_drivers[].connection` references this -metadata. Credentials are stored as forge-level secrets (not checked +Jira API credentials as forge secrets and writes poll driver connection +metadata to `.fullsend/config.yaml`. The command resolves Jira +credentials via environment variables or CLI flags and supports +`--dry-run`. + +Enrollment writes Jira connection metadata (project key, host URL) +directly into the poll driver's `poll.input_drivers[].connection` +block in `.fullsend/config.yaml`, consistent with ADR 0063's existing +schema. Credentials are stored as forge-level secrets (not checked into the repository), compatible with [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)'s credential isolation model. Ensuring credentials stay outside the agent @@ -82,9 +83,13 @@ admin's responsibility. [ADR 0055](0055-unified-env-var-delivery.md), pre/post scripts), not by enrollment. - The Jira-token portion of ADR 0063's open question on credential - placement is resolved for the enrollment path; poll drivers read - connection metadata from `integrations.jira`. Forge-native credentials - (`GITHUB_TOKEN`, App creds) remain unaddressed by this ADR. + placement is resolved for the enrollment path; the CLI writes + connection metadata directly into `poll.input_drivers[].connection`. + No separate `integrations.jira` config key is introduced — if a + push-based dispatch path (e.g. Jira Automation webhooks) is adopted + later, a future ADR can introduce integration-level config at that + point. Forge-native credentials (`GITHUB_TOKEN`, App creds) remain + unaddressed by this ADR. - Jira API token rotation is the repo admin's responsibility — re-running `fullsend jira enroll` with a new token is designed to update the forge secret. Per-forge idempotency verification is tracked diff --git a/docs/architecture.md b/docs/architecture.md index 63c392e593..6fabc8ae7c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,7 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -- Jira project enrollment: `fullsend jira enroll` CLI command provisions Jira API credentials as forge secrets and writes enrollment metadata to `.fullsend/config.yaml` under `integrations.jira` ([ADR 0079](ADRs/0079-jira-project-enrollment-via-cli.md)). Poll drivers ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)) reference this metadata for connection config; repo-to-issue association is handled by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). +- Jira project enrollment: `fullsend jira enroll` CLI command provisions Jira API credentials as forge secrets and writes connection metadata into the poll driver's `poll.input_drivers[].connection` block in `.fullsend/config.yaml` ([ADR 0079](ADRs/0079-jira-project-enrollment-via-cli.md)). Repo-to-issue association is handled by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). **Open questions:** From d1a7bd7b597f2064ca81fd889624a8df40671c47 Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Fri, 31 Jul 2026 15:58:30 +0530 Subject: [PATCH 10/11] docs(adr): specify concrete credential model for Jira enrollment Address reviewer feedback on auth schema, CLI flag exposure, invocation model, PoC limitations, and enrollment term overloading: - Specify credential shape: cloud_id + project_key in poll driver connection config; JIRA_EMAIL + JIRA_API_TOKEN as forge secrets - Document scoped-token auth against api.atlassian.com gateway with Cloud ID resolved at enrollment time from host URL - Restrict credential input to env vars only (no CLI flags) to avoid shell-history/process-list exposure - Clarify target-repo operates on remote owner/repo via forge API - Acknowledge PoC limitations (GitHub-specific, push-based) and narrow ADR scope to credential provisioning + poll-driver config - Disambiguate from EnrollmentLayer (ADR 0006) in both ADR text and architecture.md Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Co-authored-by: Cursor --- .../0079-jira-project-enrollment-via-cli.md | 86 +++++++++++++------ docs/architecture.md | 2 +- 2 files changed, 62 insertions(+), 26 deletions(-) diff --git a/docs/ADRs/0079-jira-project-enrollment-via-cli.md b/docs/ADRs/0079-jira-project-enrollment-via-cli.md index c1d28d8cde..56f5715e1b 100644 --- a/docs/ADRs/0079-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0079-jira-project-enrollment-via-cli.md @@ -30,9 +30,21 @@ to reach the poll driver and agent pre-scripts, but no ADR specifies how those credentials are provisioned or where enrollment metadata lives. A proof-of-concept ([manish-jira](https://github.com/rh-hemartin-fullsendai/manish-jira)) -validated end-to-end Jira-to-agent dispatch. The enrollment steps -(credential provisioning, config updates) were entirely manual; the -CLI automates them. +validated end-to-end Jira-to-agent dispatch using classic (unscoped) +API tokens against `.atlassian.net`. The PoC is GitHub-specific +and uses push-based `repository_dispatch`; this ADR intentionally +narrows scope to credential provisioning and poll-driver config, +deferring dispatch mechanics to +[ADR 0063](0063-polling-based-work-discovery.md). The enrollment steps +were entirely manual in the PoC; the CLI automates them. + +Atlassian is deprecating unscoped API tokens. Scoped tokens require the +`api.atlassian.com` gateway with a Cloud ID in the URL +(`https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/...`) and +Basic auth (`email:token`). The Cloud ID is a stable site identifier +resolvable from any tenant hostname via +`https:///_edge/tenant_info`; the CLI resolves it once at +enrollment time. ## Options @@ -49,33 +61,52 @@ config. Follows established CLI patterns (cobra subcommands, `--dry-run`). ## Decision -Add a `fullsend jira enroll ` CLI command that provisions -Jira API credentials as forge secrets and writes poll driver connection -metadata to `.fullsend/config.yaml`. The command resolves Jira -credentials via environment variables or CLI flags and supports -`--dry-run`. - -Enrollment writes Jira connection metadata (project key, host URL) -directly into the poll driver's `poll.input_drivers[].connection` -block in `.fullsend/config.yaml`, consistent with ADR 0063's existing -schema. Credentials are stored as forge-level secrets (not checked -into the repository), compatible with +Add a `fullsend jira enroll ` CLI command that operates on +a remote `owner/repo` target via the forge API (no local clone +required). The command accepts Jira credentials via environment +variables (`JIRA_HOST`, `JIRA_EMAIL`, `JIRA_API_TOKEN`) and supports +`--dry-run`. Credentials are never accepted via CLI flags to avoid +shell-history and process-list exposure. + +The CLI resolves the Jira Cloud ID from the host URL at enrollment +time (`https:///_edge/tenant_info`) and writes two non-secret +values into the poll driver's `poll.input_drivers[].connection` block +in `.fullsend/config.yaml`: + +```yaml +poll: + input_drivers: + - type: jira-poll + connection: + cloud_id: "" + project_key: EXAMPLE +``` + +Two credentials are stored as forge-level secrets (not checked into +the repository): `JIRA_EMAIL` (Atlassian account email) and +`JIRA_API_TOKEN` (scoped API token). Together these support Basic auth +against the `api.atlassian.com` gateway. This is compatible with [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)'s -credential isolation model. Ensuring credentials stay outside the agent -sandbox is the harness author's responsibility (via `env.runner` / -`env.sandbox` per [ADR 0055](0055-unified-env-var-delivery.md) and +credential isolation model. Ensuring credentials stay outside the +agent sandbox is the harness author's responsibility (via `env.runner` +/ `env.sandbox` per [ADR 0055](0055-unified-env-var-delivery.md) and pre/post scripts). Enrollment is designed to be idempotent — re-running with a new token -updates the forge secret. The enrollment scope is credentials and config only; the dispatch -mechanism is the poll driver's responsibility -([ADR 0063](0063-polling-based-work-discovery.md)), and agent-level -Jira awareness (harness `pre_script` / `post_script`) is the repo -admin's responsibility. +updates the forge secret. The enrollment scope is credentials and +config only; the dispatch mechanism is the poll driver's +responsibility ([ADR 0063](0063-polling-based-work-discovery.md)), +and agent-level Jira awareness (harness `pre_script` / +`post_script`) is the repo admin's responsibility. This is distinct +from the CLI's `EnrollmentLayer` ([ADR 0006](0006-ordered-layer-model.md)), +which manages forge-level installation scaffolding. ## Consequences -- Jira credential provisioning is automated and consistent across forges. +- Jira credential provisioning is automated and consistent across + forges. Two forge secrets (`JIRA_EMAIL`, `JIRA_API_TOKEN`) and two + config values (`cloud_id`, `project_key`) fully describe a Jira + connection. - Credentials are stored as forge secrets, compatible with [ADR 0017](0017-credential-isolation-for-sandboxed-agents.md)'s isolation model. Sandbox isolation is enforced downstream by harness @@ -90,10 +121,15 @@ admin's responsibility. later, a future ADR can introduce integration-level config at that point. Forge-native credentials (`GITHUB_TOKEN`, App creds) remain unaddressed by this ADR. +- Credentials are accepted only via environment variables, not CLI + flags, to avoid shell-history and process-list exposure. +- The Cloud ID is resolved once at enrollment time from the Jira host + URL. Runtime API calls use the `api.atlassian.com` gateway with the + stored Cloud ID, avoiding per-poll lookups. - Jira API token rotation is the repo admin's responsibility — re-running `fullsend jira enroll` with a new token is designed to - update the forge secret. Per-forge idempotency verification is tracked - as an implementation concern. + update the forge secret. Per-forge idempotency verification is + tracked as an implementation concern. - Repo-to-issue association is out of scope — the poll driver ([ADR 0063](0063-polling-based-work-discovery.md)) handles which issues route to which repositories. diff --git a/docs/architecture.md b/docs/architecture.md index 6fabc8ae7c..d0f76a2f44 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,7 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -- Jira project enrollment: `fullsend jira enroll` CLI command provisions Jira API credentials as forge secrets and writes connection metadata into the poll driver's `poll.input_drivers[].connection` block in `.fullsend/config.yaml` ([ADR 0079](ADRs/0079-jira-project-enrollment-via-cli.md)). Repo-to-issue association is handled by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). +- Jira project connection: `fullsend jira enroll` CLI command provisions Jira credentials (`JIRA_EMAIL`, `JIRA_API_TOKEN`) as forge secrets and writes `cloud_id` + `project_key` into the poll driver's `poll.input_drivers[].connection` block in `.fullsend/config.yaml` ([ADR 0079](ADRs/0079-jira-project-enrollment-via-cli.md)). This is distinct from the `EnrollmentLayer` ([ADR 0006](ADRs/0006-ordered-layer-model.md)) that manages forge-level installation scaffolding. Repo-to-issue association is handled by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). **Open questions:** From 57a1c2a4fe55d1dc39705c56e3a70d48fdda0759 Mon Sep 17 00:00:00 2001 From: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Date: Fri, 31 Jul 2026 16:11:24 +0530 Subject: [PATCH 11/11] docs(adr): rename jira enroll to jira setup to avoid verb overloading fullsend github enroll is a lightweight config toggle that does not set secrets. jira setup provisions forge secrets alongside config, so using a different verb avoids overloading the narrower existing meaning. Signed-off-by: Manish Kumar <30774250+manish-jangra@users.noreply.github.com> Co-authored-by: Cursor --- .../0079-jira-project-enrollment-via-cli.md | 22 +++++++++++-------- docs/architecture.md | 2 +- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/ADRs/0079-jira-project-enrollment-via-cli.md b/docs/ADRs/0079-jira-project-enrollment-via-cli.md index 56f5715e1b..4871ab46eb 100644 --- a/docs/ADRs/0079-jira-project-enrollment-via-cli.md +++ b/docs/ADRs/0079-jira-project-enrollment-via-cli.md @@ -1,5 +1,5 @@ --- -title: "79. Jira project enrollment via fullsend CLI" +title: "79. Jira project setup via fullsend CLI" status: Accepted relates_to: - agent-infrastructure @@ -10,7 +10,7 @@ topics: - credentials --- -# 79. Jira project enrollment via fullsend CLI +# 79. Jira project setup via fullsend CLI Date: 2026-07-09 @@ -54,14 +54,18 @@ Operators follow a guide to create forge secrets and edit `.fullsend/config.yaml` by hand. Rejected — error-prone for multi-project setups and inconsistent across forges. -### Option 2: `fullsend jira enroll` CLI command +### Option 2: `fullsend jira setup` CLI command A CLI command provisions credentials and writes poll driver connection -config. Follows established CLI patterns (cobra subcommands, `--dry-run`). +config. The verb `setup` is chosen over `enroll` to avoid overloading: +`fullsend github enroll` is a lightweight config toggle that does not +set secrets, while `jira setup` provisions forge secrets alongside +config. Follows established CLI patterns (cobra subcommands, +`--dry-run`). ## Decision -Add a `fullsend jira enroll ` CLI command that operates on +Add a `fullsend jira setup ` CLI command that operates on a remote `owner/repo` target via the forge API (no local clone required). The command accepts Jira credentials via environment variables (`JIRA_HOST`, `JIRA_EMAIL`, `JIRA_API_TOKEN`) and supports @@ -92,9 +96,9 @@ agent sandbox is the harness author's responsibility (via `env.runner` / `env.sandbox` per [ADR 0055](0055-unified-env-var-delivery.md) and pre/post scripts). -Enrollment is designed to be idempotent — re-running with a new token -updates the forge secret. The enrollment scope is credentials and -config only; the dispatch mechanism is the poll driver's +The command is designed to be idempotent — re-running with a new token +updates the forge secret. The scope is credentials and config only; +the dispatch mechanism is the poll driver's responsibility ([ADR 0063](0063-polling-based-work-discovery.md)), and agent-level Jira awareness (harness `pre_script` / `post_script`) is the repo admin's responsibility. This is distinct @@ -127,7 +131,7 @@ which manages forge-level installation scaffolding. URL. Runtime API calls use the `api.atlassian.com` gateway with the stored Cloud ID, avoiding per-poll lookups. - Jira API token rotation is the repo admin's responsibility — - re-running `fullsend jira enroll` with a new token is designed to + re-running `fullsend jira setup` with a new token is designed to update the forge secret. Per-forge idempotency verification is tracked as an implementation concern. - Repo-to-issue association is out of scope — the poll driver diff --git a/docs/architecture.md b/docs/architecture.md index d0f76a2f44..508eca094c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,7 +53,7 @@ the dedicated org-level `/.fullsend` config repo is deprecated - Dispatch version-skew resolution: per-repo `reusable-dispatch.yml` inlines stage workflow jobs directly, eliminating `@v0` references to `reusable-{stage}.yml` ([ADR 0062](ADRs/0062-dispatch-version-skew.md)). - Ready-made configuration presets: `fullsend github setup --config ` installs a vendor preset as `.fullsend/config.base.yaml` and a stub `.fullsend/config.yaml` overlay in the target repository; mint URL, inference backend, and related settings live in configuration files resolved through accessor methods, not CLI flags. Shared-infrastructure presets will reduce per-adopter enrollment (target state): mint via `job_workflow_ref` trust per [ADR 0059](ADRs/0059-public-mint-mode-with-wildcard-allowlists.md); inference authorization model undecided ([ADR 0069](ADRs/0069-ready-made-configuration-presets.md)); enrollment remains required until follow-on ADRs land. - GitLab event dispatch: two-path model — native CI triggers (`merge_request_event`) for MR events, cron-based polling for issues/comments/labels. No external infrastructure (no webhook bridge). Bot PAT via OIDC/WIF from Secret Manager or protected CI/CD variable. Per-repo only ([ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -- Jira project connection: `fullsend jira enroll` CLI command provisions Jira credentials (`JIRA_EMAIL`, `JIRA_API_TOKEN`) as forge secrets and writes `cloud_id` + `project_key` into the poll driver's `poll.input_drivers[].connection` block in `.fullsend/config.yaml` ([ADR 0079](ADRs/0079-jira-project-enrollment-via-cli.md)). This is distinct from the `EnrollmentLayer` ([ADR 0006](ADRs/0006-ordered-layer-model.md)) that manages forge-level installation scaffolding. Repo-to-issue association is handled by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). +- Jira project connection: `fullsend jira setup` CLI command provisions Jira credentials (`JIRA_EMAIL`, `JIRA_API_TOKEN`) as forge secrets and writes `cloud_id` + `project_key` into the poll driver's `poll.input_drivers[].connection` block in `.fullsend/config.yaml` ([ADR 0079](ADRs/0079-jira-project-enrollment-via-cli.md)). This is distinct from the `EnrollmentLayer` ([ADR 0006](ADRs/0006-ordered-layer-model.md)) that manages forge-level installation scaffolding. Repo-to-issue association is handled by the poll driver design ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). **Open questions:**