Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 14 additions & 13 deletions adr/4173-issue-tracker-seam.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# ADR-4173: The issue tracker seam

**Status**: Accepted (PRD #4173, M3 landed; M4–M6 pending)
**Date**: 2026-11-11
**Status**: Accepted (PRD #4173, M4 landed; M5–M6 pending)
**Date**: 2026-11-11 (updated 2026-11-13)
**Deciders**: the maintainer + agent team
**PRD**: [prds/4173-external-issue-trackers.md](../prds/4173-external-issue-trackers.md) — the PRD carries the milestones and the Decision Log; this ADR carries the durable shape of what M3 built and the invariants a later change must keep.
**PRD**: [prds/4173-external-issue-trackers.md](../prds/4173-external-issue-trackers.md) — the PRD carries the milestones and the Decision Log; this ADR carries the durable shape of what M3 and M4 built and the invariants a later change must keep.

## Decision (summary)

Issue trackers other than the repo's forge sit behind a `Driver` in their own package, `api/internal/issuetracker`. A driver is `forge.IssueTracker` plus four connection operations. Connections live apart from forge connections (`issuetrackersvc`, table `issue_tracker_connections`) with their own base URL allowlist. The YouTrack driver adapts YouTrack's string ids inside itself, is built for exactly one project, and treats tags as user-owned objects chosen by id. Through M3 no repo can link to an issue tracker, so no behaviour changes for forges.
Issue trackers other than the repo's forge sit behind a `Driver` in their own package, `api/internal/issuetracker`. A driver is `forge.IssueTracker` plus four connection operations. Connections live apart from forge connections (`issuetrackersvc`, table `issue_tracker_connections`) with their own base URL allowlist. The YouTrack driver adapts YouTrack's string ids inside itself, is built for exactly one project, and treats tags as user-owned objects chosen by id. From M4 a repo created after the M4 migration can link to one before its first enable (D13); a repo with no link behaves as before.

Not shipped yet: the repo link, `IssueTrackerForRepo` returning an issue tracker (M4), the board and run behaviour on YouTrack (M5), and the live pass against a real YouTrack with docs (M6).
Shipped in M4: the repo link and `IssueTrackerForRepo` returning the linked issue tracker, with intake and runs from YouTrack issues. Not shipped yet: issue writes and board moves on YouTrack (M5), the web and CLI settings surfaces, docs and the live pass against a real YouTrack (M6). On a linked repo every issue write is refused with `ErrIssueWriteNotOffered`.

## Context

Expand Down Expand Up @@ -40,31 +40,32 @@ Not shipped yet: the repo link, `IssueTrackerForRepo` returning an issue tracker
- `issueIID` is YouTrack's `numberInProject`. Each per-issue call checks the issue reached is in the bound project and carries the number, so a moved issue reads as not found. YouTrack has no conditional write, so a move between that check and the write is not caught.
- `IssueNote.ID` is 0, not derived from YouTrack's string comment id. Account ids are 0, with the login kept as text.
- `ListStates` takes the project it reads, because states belong to a project.
- The nullable `issue_key` column is M4's.
- The readable id is `issues.issue_key` (`<SHORT>-<n>`), nullable with a CHECK, written only by the linked sync and NULL for forge issues.

### D14. The tag rules

- The eligibility tag is chosen by id. Its name resolves to the stored id whoever owns the tag, for reads and for writes.
- Any other name resolves only to a tag owned by the connection's account, which the driver learns from `users/me`. A missing one is created, owned by that account, with the eligibility tag's sharing settings. The eligibility tag is never created, and a drifted name never resolves to the eligibility id.
- Reads drop a tag that only shares the eligibility name.
- `ListTags` returns the tags the token can see, with owner and read/use sharing settings. `AccountCanApply` and `OthersCanApply` judge the use settings, and the owner counts as covered. A named group counts for others only with `UsersCount >= 2`; the anonymous response recorded from a real YouTrack (`testdata/youtrack_tags_recorded.json`) omits `usersCount`, so on such a response only the All Users group counts. This fails closed. Using these to refuse a link is M4.
- `ListTags` returns the tags the token can see, with owner and read/use sharing settings. `AccountCanApply` and `OthersCanApply` judge the use settings, and the owner counts as covered. A named group counts for others only with `UsersCount >= 2`; the anonymous response recorded from a real YouTrack (`testdata/youtrack_tags_recorded.json`) omits `usersCount`, so on such a response only the All Users group counts. This fails closed. The link step uses these to refuse a link (M4).
- Intake lists the eligibility tag's issues by id (`GET /api/tags/{id}/issues`), filtered on the client by the stored tag id, and `ListLabels` returns only the tags the driver can use: the stored eligibility name plus tags the connection's account owns.

## Invariants a future change must keep

- **S1. An issue tracker never gains code access.** `Driver` embeds `forge.IssueTracker`, not `forge.CodeHost`; a driver passed as a code host does not compile.
- **S2. Code-host checks stay on the forge.** The privilege check, the protected-branch check and the worker-held forge credential act on the repo's forge connection and fail closed. Nothing in M3 touches them, and no repo is linked yet to test the claim further.
- **S2. Code-host checks stay on the forge.** The privilege check, the protected-branch check and the worker-held forge credential act on the repo's forge connection and fail closed. M4 tests that a linked repo keeps them on the forge and that they fail closed with the issue tracker unreachable.
- **S3. Credentials follow the forge rules.** Sealed token with AAD and no reveal path, https-only base URL on the separate empty-by-default allowlist re-checked in `DriverFor`, redirects refused, errors redacted. The redirect, oversized-body and token-in-error cases each have a test in `api/internal/issuetracker`.
- **S4. Issue tracker text is untrusted input.** The driver bounds what it reads (response bytes, listing pages and items, nested items, label name length). Fencing of titles, descriptions and comments is done by the existing callers once a repo can link in M4; it is not exercised on YouTrack text yet.
- **S5. The worker never holds an issue tracker token.** The allowlist does not feed worker egress, and the token is opened only inside `DriverFor` in the API. The worker read routes are M4.
- **S4. Issue tracker text is untrusted input.** The driver bounds what it reads (response bytes, listing pages and items, nested items, label name length). YouTrack titles, descriptions and comments go through the same `issueinput` fencing as forge text; an oversized description is refused and an oversized comment by the connection's own account is cut to the same bound as on a forge, while an unmapped author's comment is withheld; M4 tests each.
- **S5. The worker never holds an issue tracker token.** The allowlist does not feed worker egress, and the token is opened only inside `DriverFor` in the API. The worker read routes go through the API's resolver, so the worker never holds the token.

## Open questions for M6's live pass

- Whether YouTrack accepts `readSharingSettings` and `tagSharingSettings` in the tag-create body. The fake accepts them; no real server has been asked.
- Whether an authenticated token receives `usersCount` on a tag's sharing groups (the anonymous recording has none).
- Whether the server query `tag: {name}` resolves every tag of that name, including ones owned by others. The client side filters by id, so a wrong answer here would drop issues, not mis-tag them.
- Whether the id-scoped listing `GET /api/tags/{id}/issues` behaves on a real instance as the fake and YouTrack's documented shape say. The earlier question, whether `tag: {name}` resolves every tag of that name, is settled: intake sends no tag name in a search query (PRD Decision Log 2026-11-12). If the listing proves unusable, the documented fallback walks the whole project and filters by stored id, bounded by the same listing ceilings.

## Consequences

- Forge drivers, the neutral types and every caller are unchanged. A second tracker (Asana) is the real test of the seam: YouTrack specifics (the id adapter, the tag rules) must stay inside its driver.
- Forge drivers and the neutral types are unchanged; callers resolve their issue side through the owner-scoped resolvers, and on a repo with no link they behave as before. A second issue tracker (Asana) is the real test of the seam: YouTrack specifics (the id adapter, the tag rules) must stay inside its driver.
- Operators get one new empty setting. Until it is set no issue tracker connection can be created, and uzi boots as before.
- The `projectID` guard is one half of a binding. M4 owns the other half, the resolver.
- The `projectID` guard is one half of a binding. M4 added the other half, the resolver (`IssueTrackerForRepo`, owner-scoped).
2 changes: 1 addition & 1 deletion agent/src/linked-issue.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ const ISSUE_KEY_RE = /^[A-Za-z][A-Za-z0-9_]*-[1-9][0-9]*$/u;
const ISSUE_KEY_MAX = 64;

/** What a linked run's text says when its key is absent or malformed. */
export const LINKED_ISSUE_FALLBACK_LABEL = "the linked issue";
const LINKED_ISSUE_FALLBACK_LABEL = "the linked issue";

export function linkedIssueKey(claim: { issue_key?: unknown }): LinkedIssue {
const raw = claim.issue_key;
Expand Down
2 changes: 1 addition & 1 deletion api/cmd/server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -1007,7 +1007,7 @@ func run() error {
h := handler.New(pool, q, cfg, box, svc, wsvc, pcheck, liveHub, settingsCache)
// External issue tracker connections and the repo link (PRD #4173 M4). The link and
// the reconnect rule run in transactions on the pool. An empty allowlist
// (UZI_ISSUE_TRACKER_ALLOWED_BASE_URLS) still boots: Connect then refuses every URL.
// (ISSUE_TRACKER_ALLOWED_BASE_URLS) still boots: Connect then refuses every URL.
itSvc := issuetrackersvc.New(q, box, cfg.IssueTrackerBaseURLAllowed, issuetracker.New).
UseTransactions(pool, func(tx pgx.Tx) issuetrackersvc.Querier { return q.WithTx(tx) })
h.SetIssueTrackerService(itSvc)
Expand Down
112 changes: 112 additions & 0 deletions api/internal/handler/linked_repo_d11_livedb_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
package handler

import (
"context"
"encoding/json"
"net/http"
"strings"
"testing"

"github.com/vtmocanu/uzi/api/internal/issueinput"
"github.com/vtmocanu/uzi/api/internal/issuetracker/youtracktest"
)

// PRD #4173 M4 D11 through the real run capture: comment and author mapping on a linked repo.

func (f *linkedHandlerFixture) wireRuns(t *testing.T) {
t.Helper()
f.h.wsvc.SetForges(f.h.svc)
f.h.wsvc.SetIssueSources(f.h.svc)
f.seedRunCredentials(t)
}

// Acceptance 2: a comment by an unmapped author is withheld from the stored run snapshot;
// the connection account's own comment is kept.
func TestLinkedRunSnapshotWithholdsAnUnmappedAuthorsCommentLiveDB(t *testing.T) {
f := newLinkedHandlerFixture(t, true)
f.srv.SeedComment(f.issueN, youtracktest.OtherLogin, "UNMAPPED_RAW_TEXT")
f.srv.SeedComment(f.issueN, youtracktest.BotLogin, "the account's own comment")
f.syncOK(t)
f.wireRuns(t)

rr := f.call(f.h.CreateRun, http.MethodPost, map[string]any{"issue_iid": f.issueN})
if rr.Code != http.StatusCreated {
t.Fatalf("manual run: status = %d body = %s", rr.Code, rr.Body.String())
}
var raw []byte
if err := f.pool.QueryRow(context.Background(), `SELECT issue_comments FROM runs WHERE repo_id = $1 AND issue_iid = $2`, f.repo, f.issueN).Scan(&raw); err != nil {
t.Fatal(err)
}
if strings.Contains(string(raw), "UNMAPPED_RAW_TEXT") {
t.Fatalf("an unmapped author's comment reached the stored snapshot: %s", raw)
}
var th issueinput.Thread
if err := json.Unmarshal(raw, &th); err != nil {
t.Fatal(err)
}
if len(th.Comments) != 2 {
t.Fatalf("comments = %+v, want 2", th.Comments)
}
if c := th.Comments[0]; c.AuthorUsername != youtracktest.OtherLogin || c.Body != issueinput.Placeholder || c.Reason != issueinput.Unknown {
t.Fatalf("unmapped comment = %+v", c)
}
if c := th.Comments[1]; c.AuthorUsername != youtracktest.BotLogin || c.Body != "the account's own comment" || c.Reason != "" {
t.Fatalf("the account's own comment = %+v", c)
}
}

// Acceptance 3 (manual half): an unmapped issue author never stops a manual start.
func TestLinkedUnmappedIssueAuthorManualStartIsCreatedLiveDB(t *testing.T) {
f := newLinkedHandlerFixture(t, true)
f.srv.SetReporter(f.issueN, youtracktest.OtherLogin)
f.syncOK(t)
f.wireRuns(t)

rr := f.call(f.h.CreateRun, http.MethodPost, map[string]any{"issue_iid": f.issueN})
if rr.Code != http.StatusCreated {
t.Fatalf("manual run on an unmapped author's issue: status = %d body = %s", rr.Code, rr.Body.String())
}
var n int
if err := f.pool.QueryRow(context.Background(), `SELECT count(*) FROM runs WHERE repo_id = $1 AND issue_iid = $2`, f.repo, f.issueN).Scan(&n); err != nil || n != 1 {
t.Fatalf("runs = %d (%v), want 1", n, err)
}
// The unmapped path ran: the run records the author as permission_unknown.
var reason *string
if err := f.pool.QueryRow(context.Background(), `SELECT issue_input_reason FROM runs WHERE repo_id = $1 AND issue_iid = $2`, f.repo, f.issueN).Scan(&reason); err != nil || reason == nil || *reason != "permission_unknown" {
t.Fatalf("issue_input_reason = %v (%v), want permission_unknown", reason, err)
}
}

// Acceptance 3 (scheduled half): an unmapped author's scheduled run is created but not
// auto-approved and records permission_unknown; a mapped author's is auto-approved.
func TestLinkedUnmappedIssueAuthorScheduledRunIsNotAutoApprovedLiveDB(t *testing.T) {
for _, tc := range []struct {
name string
reporter string
wantApprove bool
wantReasons string
}{
{"unmapped author", youtracktest.OtherLogin, false, issueinput.Unknown},
{"mapped author", youtracktest.BotLogin, true, ""},
} {
t.Run(tc.name, func(t *testing.T) {
f := newLinkedHandlerFixture(t, true)
f.srv.SetReporter(f.issueN, tc.reporter)
f.syncOK(t)
f.wireRuns(t)

run, err := f.h.wsvc.CreateScheduledAutopilotRun(context.Background(), f.user.ID, f.repo, f.issueN, "", nil, nil, nil, false, nil, nil)
if err != nil {
t.Fatalf("scheduled run: %v", err)
}
var approve bool
var reasons []string
if err := f.pool.QueryRow(context.Background(), `SELECT auto_approve, auto_approve_blocked_reasons FROM runs WHERE id = $1`, run.ID).Scan(&approve, &reasons); err != nil {
t.Fatal(err)
}
if approve != tc.wantApprove || strings.Join(reasons, ",") != tc.wantReasons {
t.Fatalf("auto_approve = %v reasons = %v, want %v / %q", approve, reasons, tc.wantApprove, tc.wantReasons)
}
})
}
}
61 changes: 61 additions & 0 deletions api/internal/handler/linked_repo_intake_livedb_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"strconv"
"strings"
"testing"
Expand Down Expand Up @@ -159,6 +160,66 @@ func TestLinkedRepoIncrementalSyncCachesBelowTheMarksAndNeverEvictsLiveDB(t *tes
}
}

// Acceptance 9: an incremental sync whose marks are earlier than the issue's updated time
// advances them to the newest updated time, and a later incremental sync after the issue
// moved to another project evicts nothing.
func TestLinkedRepoIncrementalSyncAdvancesEarlierMarksLiveDB(t *testing.T) {
f := newLinkedHandlerFixture(t, true)
ctx := context.Background()
early := forgesvc.Marks{PRD: time.Unix(1000, 0), Open: time.Unix(1000, 0)}
got, err := f.h.svc.SyncIssuesIncremental(ctx, f.user.ID, f.repo, 77, f.tracker(t), early)
if err != nil {
t.Fatal(err)
}
if !got.PRD.After(early.PRD) {
t.Fatalf("marks = %+v, want PRD advanced past %v", got, early.PRD)
}
// The PRD mark advances to exactly the newest updated time the walk returned.
row, ok := f.issueRow(t, f.issueN)
if !ok {
t.Fatal("the incremental sync did not cache the issue")
}
if !got.PRD.Equal(row.ForgeUpdatedAt.Time) {
t.Fatalf("PRD mark = %v, want the issue's updated time %v", got.PRD, row.ForgeUpdatedAt.Time)
}
f.srv.MoveIssue(f.issueN, youtracktest.OtherProjectID)
if _, err := f.h.svc.SyncIssuesIncremental(ctx, f.user.ID, f.repo, 77, f.tracker(t), got); err != nil {
t.Fatal(err)
}
if _, ok := f.issueRow(t, f.issueN); !ok {
t.Fatal("an incremental sync evicted the moved issue")
}
}

// Acceptance (board contract): an unlinked repo's board cards carry no issue_key member.
func TestUnlinkedBoardCardsCarryNoIssueKeyLiveDB(t *testing.T) {
ctx := context.Background()
f := newBoardWriterFixture(ctx, t, &boardWriterStub{})
mustExecT(ctx, t, f.pool, `INSERT INTO issues (repo_id, forge_issue_iid, title, state, labels, web_url, forge_updated_at, synced_at)
VALUES ($1, 5, 'plain card', 'opened', $2, 'https://forge.example/i/5', now(), now())`, f.repoID, `["`+wantUziLabel+`"]`)
rr := httptest.NewRecorder()
f.h.GetBoard(rr, boardWriterReq(f.user, f.repoID, "", ""))
if rr.Code != http.StatusOK {
t.Fatalf("board status = %d body = %s", rr.Code, rr.Body.String())
}
var body struct {
Board struct {
Cards []map[string]any `json:"cards"`
} `json:"board"`
}
if err := json.Unmarshal(rr.Body.Bytes(), &body); err != nil {
t.Fatal(err)
}
if len(body.Board.Cards) == 0 {
t.Fatalf("the board has no cards, the check would be vacuous: %s", rr.Body.String())
}
for _, c := range body.Board.Cards {
if _, has := c["issue_key"]; has {
t.Fatalf("an unlinked repo's card carries issue_key: %v", c)
}
}
}

// A failed listing evicts nothing: the cached row survives a full sync whose listing
// fails (the issue tracker is gone), and the endpoint reports the failure.
func TestLinkedRepoFailedListingEvictsNothingLiveDB(t *testing.T) {
Expand Down
24 changes: 24 additions & 0 deletions api/internal/workersvc/issue_key_claim_deleted_row_livedb_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
package workersvc

import (
"testing"

"github.com/vtmocanu/uzi/api/internal/capability"
)

// PRD #4173 M4 acceptance 12: the claim's issue key comes from the repo's project short name
// and the run's iid, so it survives the cached issues row being evicted (deleted).
func TestIssueKeyClaimSurvivesADeletedIssueRowLiveDB(t *testing.T) {
f := newCRFix(t)
f.linkFixtureRepo(t)
f.env.exec(`INSERT INTO issues (repo_id, forge_issue_iid, title, state, labels, web_url, forge_updated_at, synced_at, issue_key)
VALUES ($1, 12, 't', 'opened', '[]', 'https://yt.test/i', now(), now(), 'ABC-12')`, f.repo)
run := f.startQueuedIssueRun(t, 12)
f.env.exec(`DELETE FROM issues WHERE repo_id = $1 AND forge_issue_iid = 12`, f.repo)

capable := f.protocolWorker(t, 0, capability.IssueKeyV1)
p := f.acceptClaim(t, capable, run, "linked run whose cached issue row is gone")
if p.IssueKey != "ABC-12" {
t.Fatalf("issue_key = %q, want ABC-12", p.IssueKey)
}
}
Loading
Loading