Documentation
¶
Overview ¶
Package tracker defines a narrow, forge-agnostic interface for reading and writing issue content (title, body, comments), keyed by (project string, number int) rather than the (owner, repo string, number int) shape used by forge.Client.
forge.Client already covers this surface for GitHub and GitLab, but it stays scoped to git-hosting operations — Jira is explicitly not a forge (it has no branches, pull requests, or CI). Keying by a single project string lets a future Jira implementation use its natural project key (e.g. "PROJECT") instead of forcing an owner/repo split that Jira doesn't have; the issue number is passed separately, as with GitHub and GitLab.
This package only defines the interface and thin adapters over forge.Client (see ForgeClient). Consumers include statuscomment (run-status notifications) and reconcilestatus (orphan cleanup).
Index ¶
- Variables
- func IsNotFound(err error) bool
- func IsNotSupported(err error) bool
- func NewFakeJiraClientWithFake(baseURL string) (*JiraClient, *FakeJiraClient, error)
- type Body
- type Client
- type Comment
- type FakeJiraClient
- func (f *FakeJiraClient) CreateComment(ctx context.Context, issueIDOrKey, body string) (*jira.Comment, error)
- func (f *FakeJiraClient) CreateCommentWithProperties(_ context.Context, issueIDOrKey, body string, ...) (*jira.Comment, error)
- func (f *FakeJiraClient) DeleteComment(_ context.Context, issueIDOrKey, commentID string) error
- func (f *FakeJiraClient) GetIssue(_ context.Context, issueIDOrKey string) (*jira.Issue, error)
- func (f *FakeJiraClient) GetMyself(_ context.Context) (*jira.User, error)
- func (f *FakeJiraClient) LinkIssues(_ context.Context, inwardIssueKey, outwardIssueKey, linkTypeName string) error
- func (f *FakeJiraClient) ListComments(_ context.Context, issueIDOrKey string) ([]jira.Comment, error)
- func (f *FakeJiraClient) SetCommentProperty(_ context.Context, issueIDOrKey, commentID, propertyKey string, value any) error
- func (f *FakeJiraClient) UpdateComment(_ context.Context, issueIDOrKey, commentID, body string) error
- type FakeJiraLink
- type ForgeClient
- func (c *ForgeClient) AddCommentReaction(ctx context.Context, project string, number int, commentID string, ...) (int64, error)
- func (c *ForgeClient) AddIssueReaction(ctx context.Context, project string, number int, content string) (int64, error)
- func (c *ForgeClient) AuthenticatedUser(ctx context.Context) (string, error)
- func (c *ForgeClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
- func (c *ForgeClient) DeleteComment(ctx context.Context, project string, number int, commentID string) error
- func (c *ForgeClient) DeleteCommentReaction(ctx context.Context, project string, number int, commentID string, ...) error
- func (c *ForgeClient) DeleteIssueReaction(ctx context.Context, project string, number int, reactionID int64) error
- func (c *ForgeClient) GetIssue(ctx context.Context, project string, number int) (*Issue, error)
- func (c *ForgeClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)
- func (c *ForgeClient) MoveIssue(_ context.Context, sourceProject string, number int, targetProject string) (*MoveResult, error)
- func (c *ForgeClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
- type Issue
- type JiraClient
- func (c *JiraClient) AuthenticatedUser(ctx context.Context) (string, error)
- func (c *JiraClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
- func (c *JiraClient) CreateCommentWithMarker(ctx context.Context, project string, number int, body Body, marker string) (*Comment, error)
- func (c *JiraClient) CreateStatusComment(ctx context.Context, project string, number int, body Body, marker string, ...) (*Comment, error)
- func (c *JiraClient) DeleteComment(ctx context.Context, project string, number int, commentID string) error
- func (c *JiraClient) FindCommentByMarkerProperty(comments []jira.Comment, marker string) *jira.Comment
- func (c *JiraClient) FindStatusComment(ctx context.Context, project string, number int, marker string) (*Comment, bool, error)
- func (c *JiraClient) GetIssue(ctx context.Context, project string, number int) (*Issue, error)
- func (c *JiraClient) IsStatusComment(ctx context.Context, project string, number int, commentID string) (bool, error)
- func (c *JiraClient) LinkIssues(ctx context.Context, fromProject string, fromNumber int, toProject string, ...) error
- func (c *JiraClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)
- func (c *JiraClient) ListJiraComments(ctx context.Context, project string, number int) ([]jira.Comment, error)
- func (c *JiraClient) MigrateAndUpdateComment(ctx context.Context, project string, number int, commentID string, body Body, ...) error
- func (c *JiraClient) MoveIssue(_ context.Context, sourceProject string, number int, targetProject string) (*MoveResult, error)
- func (c *JiraClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
- func (c *JiraClient) UpdateStatusComment(ctx context.Context, project string, number int, commentID string, body Body, ...) error
- type Linker
- type MoveMethod
- type MoveResult
- type Mover
- type Reactor
- type StatusCommentClient
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound indicates a requested issue or comment was not found. Implementations of Client must return an error satisfying errors.Is(err, ErrNotFound) — checkable via IsNotFound — for missing resources, rather than requiring callers to reach into a specific tracker backend (e.g. forge.ErrNotFound) to detect this case.
var ErrNotSupported = errors.New("not supported by this tracker")
ErrNotSupported indicates the tracker backend does not support the requested operation (e.g. typed issue links on GitHub or GitLab).
var FakeJiraBot = jira.User{AccountID: "fake-bot-account-id", DisplayName: "fullsend-bot"}
FakeJiraBot is the account a FakeJiraClient posts as by default.
Functions ¶
func IsNotFound ¶
IsNotFound reports whether err indicates a requested issue or comment was not found.
func IsNotSupported ¶ added in v0.46.0
IsNotSupported reports whether err indicates the tracker backend does not support the requested operation.
func NewFakeJiraClientWithFake ¶ added in v0.40.0
func NewFakeJiraClientWithFake(baseURL string) (*JiraClient, *FakeJiraClient, error)
NewFakeJiraClientWithFake returns both the tracker.Client and the underlying FakeJiraClient, giving tests access to the fake's control fields (e.g. PropertyError for permission failure simulation).
Types ¶
type Body ¶
type Body string
Body is Markdown-formatted issue/comment text, as produced by GitHub and GitLab. Jira doesn't speak Markdown — its v3 API requires comment and description bodies in Atlassian Document Format (ADF) and rejects plain strings outright. A Jira Client implementation is responsible for converting Body to and from ADF; a naive pass-through (wrapping the raw Markdown string in a single ADF text node) doesn't just lose formatting, it actively corrupts content — Jira's plain-text rendering path interprets stray Markdown characters (e.g. braces in code samples) as wiki-markup and mangles the surrounding text.
type Client ¶
type Client interface {
// GetIssue returns the issue identified by project and number.
GetIssue(ctx context.Context, project string, number int) (*Issue, error)
// ListComments returns all comments on the issue identified by project and number.
ListComments(ctx context.Context, project string, number int) ([]Comment, error)
// CreateComment adds a new comment with the given body to the issue.
CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
// UpdateComment updates the body of commentID on the issue (project, number).
// number is included because Jira requires the issue key to update a comment.
UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
// DeleteComment removes the comment identified by commentID from the issue.
// number is included because Jira requires the issue key to delete a comment.
DeleteComment(ctx context.Context, project string, number int, commentID string) error
}
Client abstracts issue-content read/write operations across trackers (GitHub, GitLab, and eventually Jira). Project identifies the issue's container: "owner/repo" for GitHub/GitLab, a Jira project key for Jira.
Implementations must return an error satisfying IsNotFound when the requested issue or comment doesn't exist.
type Comment ¶
Comment represents a comment on an issue.
ID is a string for JSON round-tripping safety and to allow for non-numeric IDs from a possible future tracker, even though GitHub, GitLab, and Jira comment IDs are all numeric under the hood. Callers that need to update a comment pass the ID back verbatim via UpdateComment.
type FakeJiraClient ¶ added in v0.37.0
type FakeJiraClient struct {
Issues map[string]*jira.Issue
Comments map[string][]jira.Comment
// CommentProperties maps "issueKey/commentID" to a map of
// propertyKey -> value, mirroring Jira's per-comment entity
// property store.
CommentProperties map[string]map[string]json.RawMessage
CreatedBody string
UpdatedIssueKey string
UpdatedCommentID string
UpdatedBody string
// PropertyError, when non-nil, is returned by SetCommentProperty
// to simulate permission failures.
PropertyError error
// UpdateError, when non-nil, is returned by UpdateComment to
// simulate update failures.
UpdateError error
// Myself is the account GetMyself returns and new comments are
// authored by; the zero value means FakeJiraBot. MyselfError, when
// non-nil, is returned by GetMyself.
Myself jira.User
MyselfError error
// Links records every LinkIssues call in order. LinkError, when
// non-nil, is returned by LinkIssues instead of recording the link.
Links []FakeJiraLink
LinkError error
}
FakeJiraClient is an in-memory fake implementing the jiraClient interface, exported (unlike its ecosystem forge.FakeClient counterpart, which lives alongside it) so tests in other packages can exercise tracker.Client's Jira path — including its real jira.MarkdownToADF/ADFToMarkdown round-trip — without a live Jira instance. CreateComment/UpdateComment store the body as real ADF (mirroring Jira echoing back what it stored), so ListComments/GetIssue read it back through the same escaping/decoding logic a live Jira instance would apply.
func (*FakeJiraClient) CreateComment ¶ added in v0.37.0
func (*FakeJiraClient) CreateCommentWithProperties ¶ added in v0.40.0
func (f *FakeJiraClient) CreateCommentWithProperties(_ context.Context, issueIDOrKey, body string, properties []jira.CommentProperty) (*jira.Comment, error)
func (*FakeJiraClient) DeleteComment ¶ added in v0.40.0
func (f *FakeJiraClient) DeleteComment(_ context.Context, issueIDOrKey, commentID string) error
func (*FakeJiraClient) LinkIssues ¶ added in v0.46.0
func (f *FakeJiraClient) LinkIssues(_ context.Context, inwardIssueKey, outwardIssueKey, linkTypeName string) error
func (*FakeJiraClient) ListComments ¶ added in v0.37.0
func (*FakeJiraClient) SetCommentProperty ¶ added in v0.40.0
func (*FakeJiraClient) UpdateComment ¶ added in v0.37.0
func (f *FakeJiraClient) UpdateComment(_ context.Context, issueIDOrKey, commentID, body string) error
type FakeJiraLink ¶ added in v0.46.0
FakeJiraLink is an issue link recorded by FakeJiraClient.LinkIssues.
type ForgeClient ¶
type ForgeClient struct {
// contains filtered or unexported fields
}
ForgeClient adapts a forge.Client to the tracker.Client interface. It works for both the GitHub and GitLab forge.Client implementations, since forge.Client already abstracts over the two — this adapter only needs to split the tracker's single "project" string back into the owner/repo pair that forge.Client expects, and convert forge.IssueComment's numeric ID to the string form tracker.Comment uses.
func NewForgeClient ¶
func NewForgeClient(fc forge.Client) *ForgeClient
NewForgeClient returns a tracker.Client backed by fc.
func (*ForgeClient) AddCommentReaction ¶ added in v0.40.0
func (c *ForgeClient) AddCommentReaction(ctx context.Context, project string, number int, commentID string, content string) (int64, error)
AddCommentReaction implements Reactor by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) AddIssueReaction ¶ added in v0.40.0
func (c *ForgeClient) AddIssueReaction(ctx context.Context, project string, number int, content string) (int64, error)
AddIssueReaction implements Reactor by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) AuthenticatedUser ¶ added in v0.44.0
func (c *ForgeClient) AuthenticatedUser(ctx context.Context) (string, error)
AuthenticatedUser returns the login the underlying forge client is authenticated as, so a caller can tell the bot's own comments from anyone else's.
func (*ForgeClient) CreateComment ¶
func (c *ForgeClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
CreateComment implements Client by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) DeleteComment ¶ added in v0.40.0
func (c *ForgeClient) DeleteComment(ctx context.Context, project string, number int, commentID string) error
DeleteComment implements Client by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) DeleteCommentReaction ¶ added in v0.40.0
func (c *ForgeClient) DeleteCommentReaction(ctx context.Context, project string, number int, commentID string, reactionID int64) error
DeleteCommentReaction implements Reactor by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) DeleteIssueReaction ¶ added in v0.40.0
func (c *ForgeClient) DeleteIssueReaction(ctx context.Context, project string, number int, reactionID int64) error
DeleteIssueReaction implements Reactor by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) GetIssue ¶
GetIssue implements Client by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) ListComments ¶
func (c *ForgeClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)
ListComments implements Client by splitting project into owner/repo for the underlying forge call.
func (*ForgeClient) MoveIssue ¶ added in v0.48.0
func (c *ForgeClient) MoveIssue(_ context.Context, sourceProject string, number int, targetProject string) (*MoveResult, error)
MoveIssue implements Mover. Both forge-backed trackers have a native move — GitHub's GraphQL transferIssue mutation, GitLab's POST /projects/:id/issues/:iid/move — but neither is exposed on forge.Client yet, so there is nothing for this adapter to delegate to. It reports ErrNotSupported rather than reporting a move it did not perform.
func (*ForgeClient) UpdateComment ¶
func (c *ForgeClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
UpdateComment implements Client. number is unused here: forge.Client's UpdateIssueComment takes only a comment ID, which is sufficient for GitHub (comment IDs are globally unique within the repo). GitLab actually needs the issue/MR IID to address a note directly — see gitlab.LiveClient.updateOrDeleteNote — but forge.Client's UpdateIssueComment doesn't expose one, so the GitLab path still falls back to that method's documented scan. Jira needs the issue key for an unrelated reason: it isn't a forge.Client implementation at all.
type Issue ¶
type Issue struct {
Number int
Title string
Body Body
URL string
Labels []string
// IssueType is the tracker's issue type name (e.g. "Bug", "Story").
// Set by the Jira client; empty for trackers that don't report one.
IssueType string
// CustomFields maps tracker-specific custom field IDs (e.g. Jira's
// "customfield_10875") to their raw JSON values. Set by the Jira
// client; nil for GitHub and GitLab.
CustomFields map[string]json.RawMessage
}
Issue represents an issue's content, independent of the tracker backend.
type JiraClient ¶ added in v0.37.0
type JiraClient struct {
// contains filtered or unexported fields
}
JiraClient adapts a Jira client to tracker.Client. project is a Jira project key (e.g. "PROJ"); (project, number) maps to the issue key "PROJ-123".
func NewFakeJiraClient ¶ added in v0.37.0
func NewFakeJiraClient(baseURL string) (*JiraClient, error)
NewFakeJiraClient returns a tracker.Client backed by an in-memory fake that round-trips comment bodies through the real jira.MarkdownToADF/ADFToMarkdown conversions, for tests that need to exercise Jira-specific markdown quirks (e.g. mdEscaper) without a live Jira instance.
func NewJiraClient ¶ added in v0.37.0
func NewJiraClient(jc jiraClient, baseURL string) (*JiraClient, error)
NewJiraClient returns a tracker.Client backed by jc. baseURL is the Jira instance's base URL (e.g. "https://acme.atlassian.net"), used to build issue browse URLs. Returns an error if baseURL embeds credentials (https://user:token@host): those would otherwise propagate into every Issue.URL this client returns, which are commonly logged or displayed.
func (*JiraClient) AuthenticatedUser ¶ added in v0.44.0
func (c *JiraClient) AuthenticatedUser(ctx context.Context) (string, error)
AuthenticatedUser returns the account ID this client is authenticated as (GET /myself), so a caller can tell its own comments from anyone else's by Comment.Author.AccountID. Display names are not identities.
func (*JiraClient) CreateComment ¶ added in v0.37.0
func (c *JiraClient) CreateComment(ctx context.Context, project string, number int, body Body) (*Comment, error)
CreateComment implements Client. The returned Comment's Body is ADFToMarkdown(comment.Body), the same representation ListComments uses, so tracker.Comment.Body has a stable meaning regardless of which method produced it.
func (*JiraClient) CreateCommentWithMarker ¶ added in v0.40.0
func (c *JiraClient) CreateCommentWithMarker(ctx context.Context, project string, number int, body Body, marker string) (*Comment, error)
CreateCommentWithMarker creates a comment with the sticky marker stored as a Jira comment entity property instead of embedded in the visible ADF body. This keeps implementation bookkeeping out of the user-visible conversation on Jira (which lacks HTML comments and would render the marker as plain text).
func (*JiraClient) CreateStatusComment ¶ added in v0.40.0
func (c *JiraClient) CreateStatusComment(ctx context.Context, project string, number int, body Body, marker string, terminal bool) (*Comment, error)
CreateStatusComment implements StatusCommentClient by storing run identity and terminal state in a Jira comment entity property.
func (*JiraClient) DeleteComment ¶ added in v0.40.0
func (c *JiraClient) DeleteComment(ctx context.Context, project string, number int, commentID string) error
DeleteComment implements Client.
func (*JiraClient) FindCommentByMarkerProperty ¶ added in v0.40.0
func (c *JiraClient) FindCommentByMarkerProperty(comments []jira.Comment, marker string) *jira.Comment
FindCommentByMarkerProperty returns the first comment that carries the sticky marker as a comment entity property, or nil if none is found. This is the property-based equivalent of the body-scanning approach used for GitHub/GitLab.
If no property match is found, a legacy fallback scans comment bodies for the marker string (the old behavior before property-based storage). This allows transparent migration: the first update to a legacy comment will set the property and strip the marker from the body.
func (*JiraClient) FindStatusComment ¶ added in v0.40.0
func (c *JiraClient) FindStatusComment(ctx context.Context, project string, number int, marker string) (*Comment, bool, error)
FindStatusComment implements StatusCommentClient. Property lookup is the primary path; visible-body scanning keeps pre-property comments compatible.
func (*JiraClient) IsStatusComment ¶ added in v0.40.0
func (c *JiraClient) IsStatusComment(ctx context.Context, project string, number int, commentID string) (bool, error)
IsStatusComment implements StatusCommentClient. The legacy body check keeps timeline analysis correct while older marker-bearing comments are present.
func (*JiraClient) LinkIssues ¶ added in v0.46.0
func (c *JiraClient) LinkIssues(ctx context.Context, fromProject string, fromNumber int, toProject string, toNumber int, linkType string) error
LinkIssues implements Linker. The from issue is sent as Jira's inwardIssue and the to issue as its outwardIssue, so Jira records the link in the link type's outward direction: for "Blocks", the from issue blocks the to issue.
func (*JiraClient) ListComments ¶ added in v0.37.0
func (c *JiraClient) ListComments(ctx context.Context, project string, number int) ([]Comment, error)
ListComments implements Client.
func (*JiraClient) ListJiraComments ¶ added in v0.40.0
func (c *JiraClient) ListJiraComments(ctx context.Context, project string, number int) ([]jira.Comment, error)
ListJiraComments returns the raw jira.Comment objects (including entity properties) for use by FindCommentByMarkerProperty. This is separate from ListComments because the generic tracker.Comment type does not carry Jira-specific property data.
func (*JiraClient) MigrateAndUpdateComment ¶ added in v0.40.0
func (c *JiraClient) MigrateAndUpdateComment(ctx context.Context, project string, number int, commentID string, body Body, marker string) error
MigrateAndUpdateComment updates a comment's body and ensures the sticky marker is stored as a comment entity property. If the comment was found via the legacy body-text path (no property set), this also sets the property — transparently migrating the comment to the property-based scheme.
The body written to Jira has the marker stripped (unlike GitHub/GitLab where the marker is an invisible HTML comment). The caller should pass the body without the marker prefix.
func (*JiraClient) MoveIssue ¶ added in v0.48.0
func (c *JiraClient) MoveIssue(_ context.Context, sourceProject string, number int, targetProject string) (*MoveResult, error)
MoveIssue implements Mover. Jira Cloud has no synchronous per-issue move: relocating an issue means submitting an asynchronous bulk-move task, polling it to a terminal state, and resolving the new issue key, with field mappings to negotiate whenever the destination project's issue types, workflow, or mandatory fields differ from the source's. None of that is implemented yet, so this reports ErrNotSupported.
func (*JiraClient) UpdateComment ¶ added in v0.37.0
func (c *JiraClient) UpdateComment(ctx context.Context, project string, number int, commentID string, body Body) error
UpdateComment implements Client. Unlike GitHub/GitLab, Jira's update-comment endpoint needs the issue key, which is why number is part of the signature here.
func (*JiraClient) UpdateStatusComment ¶ added in v0.40.0
func (c *JiraClient) UpdateStatusComment(ctx context.Context, project string, number int, commentID string, body Body, marker string, terminal bool) error
UpdateStatusComment implements StatusCommentClient. Writing the property first preserves discoverability if the subsequent body update fails.
type Linker ¶ added in v0.46.0
type Linker interface {
// LinkIssues creates a link of type linkType from the issue
// (fromProject, fromNumber) to the issue (toProject, toNumber).
// linkType is passed through verbatim; its valid values and
// direction semantics are tracker-specific (for Jira, link type
// names such as "Blocks" are instance-specific).
LinkIssues(ctx context.Context, fromProject string, fromNumber int, toProject string, toNumber int, linkType string) error
}
Linker is an optional capability for creating typed links between issues. Jira implements it with issue links; GitHub and GitLab have no first-class typed issue links and do not implement it. Consumers should type-assert their tracker.Client to Linker and report ErrNotSupported when the tracker does not implement it.
type MoveMethod ¶ added in v0.48.0
type MoveMethod string
MoveMethod names the mechanism an implementation used to relocate an issue. The two constants below are its only valid values.
const ( // MoveMethodNative means the tracker relocated the issue itself // (GitHub's transferIssue, GitLab's issue move, Jira's bulk move), // carrying its comment history to the destination. It says nothing // about what remains at the source: GitHub and Jira leave only a // redirect, while GitLab's move keeps the original as a closed issue // with system notes linking the two. Either way the old location // still leads a reader to the new one. MoveMethodNative MoveMethod = "native" // MoveMethodCloseAndRecreate means a copy was filed in the // destination and the original closed with a cross-link. The source // issue still exists, closed, and the destination issue is authored // by the bot rather than the original reporter. MoveMethodCloseAndRecreate MoveMethod = "close-and-recreate" )
type MoveResult ¶ added in v0.48.0
type MoveResult struct {
// SourceProject is the project the issue moved out of, in the form
// Client methods take: "owner/repo" for GitHub and GitLab, a project
// key for Jira.
SourceProject string
// SourceNumber is the number the issue had in SourceProject.
SourceNumber int
// DestProject is the project the issue moved into.
DestProject string
// DestNumber is the issue's number in DestProject. Trackers
// renumber a moved issue to fit the destination's sequence, so it
// generally differs from SourceNumber under either mechanism.
DestNumber int
// DestURL is the web URL of the issue at its new location.
DestURL string
// Method is the mechanism that performed the move, for audit and
// reporting. It does not imply what became of the source issue —
// see MoveMethodNative.
Method MoveMethod
}
MoveResult reports where an issue ended up after a move. It carries the source endpoint back alongside the destination so a caller describing what happened — posting provenance, reporting the move to whoever asked for it — has both sides to hand without threading the original location through itself.
type Mover ¶ added in v0.48.0
type Mover interface {
// MoveIssue relocates the issue (sourceProject, number) into
// targetProject and reports where it landed.
//
// targetProject typically originates from an agent's output, which
// is untrusted: implementations must resolve it as an exact
// canonical identifier and must not prefix- or fuzzy-match it onto
// some other project. Authorizing the destination against the
// caller's allowlist is the caller's job, not the implementation's.
//
// A failed MoveIssue is not safely retryable — a move that errored
// after the tracker had already relocated the issue would duplicate
// it on a second attempt. Implementations must not retry internally
// or fall back to another strategy; they return the error and leave
// adjudication to a human.
//
// It returns an error satisfying IsNotSupported when the tracker
// cannot move issues, and one satisfying IsNotFound when the source
// issue or the target project does not exist.
MoveIssue(ctx context.Context, sourceProject string, number int, targetProject string) (*MoveResult, error)
}
Mover is an optional capability for relocating an issue from one project to another within the same tracker. Moves do not cross tracker boundaries: GitHub transfers issues between repositories under the same owner, GitLab moves them between projects, and Jira moves them between projects on the same site, but no backend can hand an issue to another backend. Consumers should type-assert their tracker.Client to Mover and report ErrNotSupported when the tracker does not implement it, the same way they handle Linker.
Implementations relocate the issue natively where they can — GitHub's transferIssue, GitLab's issue move, Jira's bulk move — which carries its comment history to the destination. Where credentials or the backend rule that out, an implementation may instead file the issue in the destination and close the original with a cross-link; that costs the reporter's authorship and splits the history across two locations.
Neither mechanism reliably removes the source issue — GitLab's native move keeps the original as a closed issue, the same as close-and-recreate does — so callers must not read MoveResult.Method as a statement about the source. Both mechanisms do leave the old location pointing at the new one, by redirect or by cross-link, so callers generally need not care which ran.
Implementations are currently stubs that return ErrNotSupported; the per-tracker move operations land separately.
type Reactor ¶ added in v0.40.0
type Reactor interface {
// AddIssueReaction adds an emoji reaction to an issue or pull request.
// content is the reaction type (e.g. "eyes", "+1", "confused").
AddIssueReaction(ctx context.Context, project string, number int, content string) (id int64, err error)
// DeleteIssueReaction removes a previously added issue reaction by ID.
DeleteIssueReaction(ctx context.Context, project string, number int, reactionID int64) error
// AddCommentReaction adds an emoji reaction to a specific comment.
AddCommentReaction(ctx context.Context, project string, number int, commentID string, content string) (id int64, err error)
// DeleteCommentReaction removes a previously added comment reaction by ID.
DeleteCommentReaction(ctx context.Context, project string, number int, commentID string, reactionID int64) error
}
Reactor is an optional capability for adding and removing emoji reactions on issues and comments. Tracker reaction support varies: GitHub and GitLab support reactions on both issues and comments; Jira Cloud supports reactions on comments but not on issues. Because the interface includes issue-level reactions, JiraClient does not implement Reactor currently — adding Jira comment-reaction support is straightforward once needed. Consumers should type-assert their tracker.Client to Reactor before calling reaction methods and silently skip reactions when the tracker does not implement it.
type StatusCommentClient ¶ added in v0.40.0
type StatusCommentClient interface {
CreateStatusComment(ctx context.Context, project string, number int, body Body, marker string, terminal bool) (*Comment, error)
UpdateStatusComment(ctx context.Context, project string, number int, commentID string, body Body, marker string, terminal bool) error
FindStatusComment(ctx context.Context, project string, number int, marker string) (comment *Comment, terminal bool, err error)
IsStatusComment(ctx context.Context, project string, number int, commentID string) (bool, error)
}
StatusCommentClient is an optional capability for trackers that can store run-status identity and lifecycle state outside the visible comment body. Jira implements this with comment entity properties. Trackers without this capability keep using invisible HTML markers in comment bodies.