jira

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 26, 2025 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package jira provides a client for the Jira REST API.

This package supports both Jira Cloud (API v3) and Jira Server/Data Center (API v2). The client auto-detects the deployment type and uses the appropriate API version.

Authentication

The client supports multiple authentication methods:

  • API Token (Cloud): Email + API token
  • Personal Access Token (Server/DC): PAT token
  • Basic Auth (legacy): Username + password
  • OAuth 2.0 (Cloud): Client credentials

Usage 

cfg := &jira.Config{
	URL:        "https://your-domain.atlassian.net",
	Auth: jira.AuthConfig{
		Type:  jira.AuthAPIToken,
		Email: "you@example.com",
		Token: "your-api-token",
	},
}

client, err := jira.NewClient(cfg)
if err != nil {
	return err
}

issue, err := client.GetIssue(ctx, "PROJ-123")

Rich Text

Jira Cloud uses Atlassian Document Format (ADF) for rich text fields like description and comments. Jira Server uses Wiki Markup. This package provides converters between these formats and Markdown: 

// Convert Markdown to ADF for Cloud
adf := jira.MarkdownToADF("**bold** text")

// Convert Wiki Markup to Markdown
md := jira.WikiToMarkdown("*bold* text")

Error Handling

The package uses devflow/http error types for consistent error handling across integrations. Use errors.Is() to check for specific conditions: 

if errors.Is(err, http.ErrNotFound) {
	// Issue doesn't exist
}
if errors.Is(err, http.ErrRateLimited) {
	// Rate limited, check Retry-After
}

Index

Constants

View Source 
const (
	ADFNodeDoc         = "doc"
	ADFNodeParagraph   = "paragraph"
	ADFNodeText        = "text"
	ADFNodeHardBreak   = "hardBreak"
	ADFNodeHeading     = "heading"
	ADFNodeBulletList  = "bulletList"
	ADFNodeOrderedList = "orderedList"
	ADFNodeListItem    = "listItem"
	ADFNodeCodeBlock   = "codeBlock"
	ADFNodeBlockquote  = "blockquote"
	ADFNodeRule        = "rule"
	ADFNodeMention     = "mention"
	ADFNodeEmoji       = "emoji"
	ADFNodeInlineCard  = "inlineCard"
	ADFNodePanel       = "panel"
	ADFNodeTable       = "table"
	ADFNodeTableRow    = "tableRow"
	ADFNodeTableHeader = "tableHeader"
	ADFNodeTableCell   = "tableCell"
)

ADF node types

View Source 
const (
	ADFMarkStrong    = "strong"
	ADFMarkEm        = "em"
	ADFMarkStrike    = "strike"
	ADFMarkCode      = "code"
	ADFMarkUnderline = "underline"
	ADFMarkLink      = "link"
	ADFMarkTextColor = "textColor"
	ADFMarkSubSup    = "subsup"
)

ADF mark types

View Source 
const TimeFormat = "2006-01-02T15:04:05.000-0700"

TimeFormat is the standard Jira timestamp format.

Variables

View Source 
var (
	ErrConfigURLRequired       = errors.New("jira url is required")
	ErrConfigAuthTypeRequired  = errors.New("jira auth type is required")
	ErrConfigAuthTypeInvalid   = errors.New("jira auth type must be api_token, oauth2, basic, or pat")
	ErrConfigAPITokenAuth      = errors.New("api_token auth requires email and token")
	ErrConfigBasicAuth         = errors.New("basic auth requires username and password")
	ErrConfigPATAuth           = errors.New("pat auth requires token")
	ErrConfigOAuth2Auth        = errors.New("oauth2 auth requires client_id and client_secret")
	ErrConfigAPIVersionInvalid = errors.New("api_version must be auto, v2, or v3")
)

Configuration errors.

View Source 
var (
	ErrIssueNotFound    = errors.New("jira issue not found")
	ErrProjectNotFound  = errors.New("jira project not found")
	ErrIssueKeyRequired = errors.New("issue key is required")
	ErrIssueKeyInvalid  = errors.New("invalid issue key format")
)

Issue errors.

View Source 
var (
	ErrTransitionNotFound   = errors.New("transition not found for issue")
	ErrTransitionNotAllowed = errors.New("transition not allowed from current status")
	ErrTransitionIDRequired = errors.New("transition id is required")
)

Transition errors.

View Source 
var (
	ErrCommentNotFound   = errors.New("comment not found")
	ErrCommentIDRequired = errors.New("comment id is required")
)

Comment errors.

View Source 
var (
	ErrWebhookInvalidSignature = errors.New("invalid webhook signature")
	ErrWebhookInvalidPayload   = errors.New("invalid webhook payload")
	ErrWebhookEventUnknown     = errors.New("unknown webhook event type")
)

Webhook errors.

View Source 
var (
	ErrADFInvalid     = errors.New("invalid ADF document")
	ErrADFVersionOnly = errors.New("ADF version must be 1")
	ErrADFTypeInvalid = errors.New("ADF root type must be 'doc'")
)

ADF errors.

View Source 
var WebhookSignatureHeaders = []string{
	"X-Hub-Signature-256",
	"X-Atlassian-Webhook-Signature",
}

WebhookSignatureHeaders are the possible headers containing the webhook signature.

Functions

func ADFToMarkdown 

func ADFToMarkdown(doc *ADFDocument) (string, error)

ADFToMarkdown is a convenience function that converts ADF to Markdown.

func ContextWithClient 

func ContextWithClient(ctx context.Context, c *Client) context.Context

ContextWithClient adds a Jira Client to a context.

func FormatTime 

func FormatTime(t time.Time) string

FormatTime formats a time.Time as a Jira timestamp string.

func IsForbidden 

func IsForbidden(err error) bool

IsForbidden reports whether the error indicates permission was denied.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether the error indicates a resource was not found.

func IsRateLimited 

func IsRateLimited(err error) bool

IsRateLimited reports whether the error indicates rate limiting.

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable reports whether the error is transient and should be retried.

func IsUnauthorized 

func IsUnauthorized(err error) bool

IsUnauthorized reports whether the error indicates authentication failed.

func MarkdownToWiki 

func MarkdownToWiki(markdown string) string

MarkdownToWiki is a convenience function that converts Markdown to Wiki Markup.

func ParseTime 

func ParseTime(s string) (time.Time, error)

ParseTime parses a Jira timestamp string. Jira uses ISO 8601 format with timezone offset.

func ValidateIssueKey 

func ValidateIssueKey(key string) bool

ValidateIssueKey validates a Jira issue key format.

func ValidateWebhookSignature 

func ValidateWebhookSignature(body []byte, signature, secret string) bool

ValidateWebhookSignature validates a Jira webhook signature. It supports both X-Hub-Signature-256 and X-Atlassian-Webhook-Signature headers. The signature should be in the format "sha256=<hex-encoded-signature>" or just the hex-encoded signature.

func WikiToMarkdown 

func WikiToMarkdown(wiki string) string

WikiToMarkdown is a convenience function that converts Wiki Markup to Markdown.

Types

type ADFConverter 

type ADFConverter struct{}

ADFConverter handles conversion between Markdown and ADF.

func NewADFConverter 

func NewADFConverter() *ADFConverter

NewADFConverter creates a new ADF converter.

func (*ADFConverter) FromADF 

func (c *ADFConverter) FromADF(doc *ADFDocument) (string, error)

FromADF converts an ADF document to Markdown.

func (*ADFConverter) FromADFAny 

func (c *ADFConverter) FromADFAny(v any) (string, error)

FromADFAny converts an ADF document from any type (for JSON unmarshaling).

func (*ADFConverter) ToADF 

func (c *ADFConverter) ToADF(markdown string) (*ADFDocument, error)

ToADF converts Markdown text to an ADF document. This is a simplified converter that handles basic markdown.

type ADFDocument 

type ADFDocument struct {
	Version int       `json:"version"` // Always 1
	Type    string    `json:"type"`    // Always "doc"
	Content []ADFNode `json:"content"`
}

ADFDocument represents an Atlassian Document Format document. This is used for rich text fields in Jira Cloud API v3.

func MarkdownToADF 

func MarkdownToADF(markdown string) (*ADFDocument, error)

MarkdownToADF is a convenience function that converts Markdown to ADF.

func NewADFDocument 

func NewADFDocument() *ADFDocument

NewADFDocument creates a new empty ADF document.

func (*ADFDocument) AddBlockquote 

func (d *ADFDocument) AddBlockquote(text string)

AddBlockquote adds a blockquote to the document.

func (*ADFDocument) AddBulletList 

func (d *ADFDocument) AddBulletList(items []string)

AddBulletList adds a bullet list to the document.

func (*ADFDocument) AddCodeBlock 

func (d *ADFDocument) AddCodeBlock(code, language string)

AddCodeBlock adds a code block to the document.

func (*ADFDocument) AddHeading 

func (d *ADFDocument) AddHeading(level int, text string)

AddHeading adds a heading to the document.

func (*ADFDocument) AddOrderedList 

func (d *ADFDocument) AddOrderedList(items []string)

AddOrderedList adds an ordered list to the document.

func (*ADFDocument) AddParagraph 

func (d *ADFDocument) AddParagraph(text string)

AddParagraph adds a paragraph with text to the document.

func (*ADFDocument) AddRule 

func (d *ADFDocument) AddRule()

AddRule adds a horizontal rule to the document.

func (*ADFDocument) Validate 

func (d *ADFDocument) Validate() error

Validate validates the ADF document structure.

type ADFMark 

type ADFMark struct {
	Type  string         `json:"type"`
	Attrs map[string]any `json:"attrs,omitempty"`
}

ADFMark represents formatting applied to text.

type ADFNode 

type ADFNode struct {
	Type    string         `json:"type"`
	Content []ADFNode      `json:"content,omitempty"`
	Text    string         `json:"text,omitempty"`
	Marks   []ADFMark      `json:"marks,omitempty"`
	Attrs   map[string]any `json:"attrs,omitempty"`
}

ADFNode represents a node in an ADF document.

func Bold 

func Bold(text string) ADFNode

Bold creates bold text.

func Code 

func Code(text string) ADFNode

Code creates inline code text.

func Italic 

func Italic(text string) ADFNode

Italic creates italic text. 

func Link(text, url string) ADFNode

Link creates a linked text.

func Strikethrough 

func Strikethrough(text string) ADFNode

Strikethrough creates strikethrough text.

func TextWithMark 

func TextWithMark(text, markType string, attrs map[string]any) ADFNode

TextWithMark creates a text node with formatting marks.

type APIError 

type APIError struct {
	StatusCode    int               `json:"-"`
	ErrorMessages []string          `json:"errorMessages,omitempty"`
	Errors        map[string]string `json:"errors,omitempty"`
	Endpoint      string            `json:"-"`
	RequestID     string            `json:"-"`
}

APIError represents an error response from the Jira API. It wraps devhttp.APIError for consistent error handling.

func NewAPIError 

func NewAPIError(statusCode int, messages []string, fieldErrors map[string]string) *APIError

NewAPIError creates a new APIError from status code and error messages.

func (*APIError) Error 

func (e *APIError) Error() string

Error implements the error interface.

func (*APIError) IsForbidden 

func (e *APIError) IsForbidden() bool

IsForbidden returns true if this is a 403 error.

func (*APIError) IsNotFound 

func (e *APIError) IsNotFound() bool

IsNotFound returns true if this is a 404 error.

func (*APIError) IsRateLimited 

func (e *APIError) IsRateLimited() bool

IsRateLimited returns true if this is a 429 error.

func (*APIError) IsUnauthorized 

func (e *APIError) IsUnauthorized() bool

IsUnauthorized returns true if this is a 401 error.

func (*APIError) Unwrap 

func (e *APIError) Unwrap() error

Unwrap returns the underlying sentinel error based on status code.

type APIVersion 

type APIVersion string

APIVersion represents the Jira REST API version. 

const (
	APIVersionAuto APIVersion = "auto"
	APIVersionV2   APIVersion = "v2"
	APIVersionV3   APIVersion = "v3"
)

API versions supported by the Jira REST API.

type AddCommentRequest 

type AddCommentRequest struct {
	Body       any                `json:"body"` // ADF or string
	Visibility *CommentVisibility `json:"visibility,omitempty"`
}

AddCommentRequest represents a request to add a comment.

type AuthConfig 

type AuthConfig struct {
	// Type is the authentication method to use.
	Type AuthType `mapstructure:"type"`

	// Email is required for api_token auth (Cloud).
	Email string `mapstructure:"email"`

	// Token is the API token (Cloud) or PAT (Server/DC).
	Token string `mapstructure:"token"`

	// Username is required for basic auth.
	Username string `mapstructure:"username"`

	// Password is required for basic auth.
	Password string `mapstructure:"password"`

	// OAuth2 configuration (Cloud only).
	ClientID     string `mapstructure:"client_id"`
	ClientSecret string `mapstructure:"client_secret"`
	AccessToken  string `mapstructure:"access_token"`
	RefreshToken string `mapstructure:"refresh_token"`
}

AuthConfig holds authentication configuration.

type AuthType 

type AuthType string

AuthType represents the type of authentication to use. 

const (
	AuthAPIToken AuthType = "api_token" // Cloud: email + API token
	AuthOAuth2   AuthType = "oauth2"    // Cloud: OAuth 2.0
	AuthBasic    AuthType = "basic"     // Server: username + password
	AuthPAT      AuthType = "pat"       // Server/DC: Personal Access Token
)

Authentication types supported by the Jira client.

type Changelog 

type Changelog struct {
	ID    string          `json:"id"`
	Items []ChangelogItem `json:"items"`
}

Changelog represents the changelog in a webhook payload.

func (*Changelog) GetFieldChange 

func (c *Changelog) GetFieldChange(fieldName string) *ChangelogItem

GetFieldChange returns the changelog item for a specific field, or nil if not found.

func (*Changelog) HasFieldChange 

func (c *Changelog) HasFieldChange(fieldName string) bool

HasFieldChange checks if the changelog contains a change for the specified field.

type ChangelogItem 

type ChangelogItem struct {
	Field      string `json:"field"`
	FieldType  string `json:"fieldtype"`
	FieldID    string `json:"fieldId,omitempty"`
	From       string `json:"from,omitempty"`
	FromString string `json:"fromString,omitempty"`
	To         string `json:"to,omitempty"`
	ToString   string `json:"toString,omitempty"`
}

ChangelogItem represents a single change in the changelog.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides access to the Jira REST API.

func ClientFromContext 

func ClientFromContext(ctx context.Context) *Client

ClientFromContext extracts a Jira Client from a context. Returns nil if no Client is present.

func NewClient 

func NewClient(cfg *Config, opts ...ClientOption) (*Client, error)

NewClient creates a new Jira client.

func (*Client) APIVersionInUse 

func (c *Client) APIVersionInUse() APIVersion

APIVersionInUse returns the API version being used.

func (*Client) AddComment 

func (c *Client) AddComment(ctx context.Context, key string, body any) (*Comment, error)

AddComment adds a comment to an issue. 

func (c *Client) AddRemoteLink(ctx context.Context, key string, link *RemoteLink) (*RemoteLink, error)

AddRemoteLink adds a remote link to an issue.

func (*Client) CreateIssue 

func (c *Client) CreateIssue(ctx context.Context, createReq *CreateIssueRequest) (*CreateIssueResponse, error)

CreateIssue creates a new issue.

func (*Client) DeploymentTypeDetected 

func (c *Client) DeploymentTypeDetected() DeploymentType

DeploymentTypeDetected returns the detected deployment type.

func (*Client) DetectDeployment 

func (c *Client) DetectDeployment(ctx context.Context) (DeploymentType, error)

DetectDeployment detects the Jira deployment type by calling serverInfo.

func (*Client) GetComments 

func (c *Client) GetComments(ctx context.Context, key string) ([]Comment, error)

GetComments retrieves comments for an issue.

func (*Client) GetIssue 

func (c *Client) GetIssue(ctx context.Context, key string) (*Issue, error)

GetIssue retrieves an issue by key. 

func (c *Client) GetRemoteLinks(ctx context.Context, key string) ([]RemoteLink, error)

GetRemoteLinks retrieves remote links for an issue.

func (*Client) GetServerInfo 

func (c *Client) GetServerInfo(ctx context.Context) (*ServerInfo, error)

GetServerInfo fetches server information.

func (*Client) GetTransitions 

func (c *Client) GetTransitions(ctx context.Context, key string) ([]Transition, error)

GetTransitions gets available transitions for an issue.

func (*Client) IsCloud 

func (c *Client) IsCloud() bool

IsCloud returns true if connected to Jira Cloud.

func (*Client) RateLimitRemaining 

func (c *Client) RateLimitRemaining() int

RateLimitRemaining returns the remaining rate limit capacity. Returns -1 if unknown.

func (*Client) SearchIssues 

func (c *Client) SearchIssues(ctx context.Context, jql string, opts *SearchOptions) (*SearchResponse, error)

SearchIssues searches for issues using JQL.

func (*Client) ServerInfoCached 

func (c *Client) ServerInfoCached() *ServerInfo

ServerInfoCached returns the cached server info, if available.

func (*Client) TransitionIssue 

func (c *Client) TransitionIssue(ctx context.Context, key, transitionID string) error

TransitionIssue transitions an issue to a new status.

func (*Client) TransitionIssueByName 

func (c *Client) TransitionIssueByName(ctx context.Context, key, transitionName string) error

TransitionIssueByName finds and executes a transition by name.

func (*Client) UpdateIssue 

func (c *Client) UpdateIssue(ctx context.Context, key string, fields map[string]any) error

UpdateIssue updates an issue's fields.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures the client.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

type CloudConverter 

type CloudConverter struct {
	// contains filtered or unexported fields
}

CloudConverter implements RichTextConverter for Jira Cloud (ADF).

func NewCloudConverter 

func NewCloudConverter() *CloudConverter

NewCloudConverter creates a converter for Jira Cloud.

func (*CloudConverter) FromJira 

func (c *CloudConverter) FromJira(content any) (string, error)

FromJira converts ADF to Markdown.

func (*CloudConverter) ToJira 

func (c *CloudConverter) ToJira(markdown string) (any, error)

ToJira converts Markdown to ADF.

type Comment 

type Comment struct {
	ID           string             `json:"id"`
	Self         string             `json:"self,omitempty"`
	Author       *User              `json:"author,omitempty"`
	UpdateAuthor *User              `json:"updateAuthor,omitempty"`
	Body         any                `json:"body"` // ADF (v3) or string (v2)
	Created      string             `json:"created"`
	Updated      string             `json:"updated"`
	Visibility   *CommentVisibility `json:"visibility,omitempty"`
}

Comment represents a Jira comment.

func (*Comment) CreatedTime 

func (c *Comment) CreatedTime() (time.Time, error)

CreatedTime parses and returns the Created timestamp.

func (*Comment) UpdatedTime 

func (c *Comment) UpdatedTime() (time.Time, error)

UpdatedTime parses and returns the Updated timestamp.

type CommentVisibility 

type CommentVisibility struct {
	Type  string `json:"type"`  // "group" or "role"
	Value string `json:"value"` // group name or role name
}

CommentVisibility represents comment visibility restrictions.

type CommentsResponse 

type CommentsResponse struct {
	StartAt    int       `json:"startAt"`
	MaxResults int       `json:"maxResults"`
	Total      int       `json:"total"`
	Comments   []Comment `json:"comments"`
}

CommentsResponse represents the response from the comments endpoint.

type Component 

type Component struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Self        string `json:"self,omitempty"`
}

Component represents a project component.

type ComponentRef 

type ComponentRef struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
}

ComponentRef references a component by name or ID.

type Config 

type Config struct {
	// URL is the base URL of the Jira instance.
	// For Cloud: https://your-domain.atlassian.net
	// For Server: https://jira.your-company.com
	URL string `mapstructure:"url"`

	// APIVersion specifies which API version to use.
	// "auto" (default) detects based on deployment type.
	// "v3" for Cloud, "v2" for Server/DC.
	APIVersion APIVersion `mapstructure:"api_version"`

	// Auth contains authentication configuration.
	Auth AuthConfig `mapstructure:"auth"`

	// HTTP contains HTTP client configuration.
	HTTP HTTPConfig `mapstructure:"http"`

	// RateLimit contains rate limiting configuration.
	RateLimit RateLimitConfig `mapstructure:"rate_limit"`
}

Config holds the configuration for the Jira client.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone returns a deep copy of the config.

func (*Config) GetAPIVersion 

func (c *Config) GetAPIVersion() APIVersion

GetAPIVersion returns the effective API version. If APIVersion is "auto" or empty, returns the default based on detection.

func (*Config) Validate 

func (c *Config) Validate() error

Validate validates the configuration.

type CreateIssueFields 

type CreateIssueFields struct {
	Project     ProjectRef     `json:"project"`
	IssueType   IssueTypeRef   `json:"issuetype"`
	Summary     string         `json:"summary"`
	Description any            `json:"description,omitempty"` // ADF or string
	Priority    *PriorityRef   `json:"priority,omitempty"`
	Assignee    *UserRef       `json:"assignee,omitempty"`
	Labels      []string       `json:"labels,omitempty"`
	Components  []ComponentRef `json:"components,omitempty"`
	FixVersions []VersionRef   `json:"fixVersions,omitempty"`
	DueDate     string         `json:"duedate,omitempty"`
	Parent      *IssueRef      `json:"parent,omitempty"`

	// Custom fields
	CustomFields map[string]any `json:"-"`
}

CreateIssueFields represents the fields for creating an issue.

type CreateIssueRequest 

type CreateIssueRequest struct {
	Fields CreateIssueFields `json:"fields"`
}

CreateIssueRequest represents a request to create an issue.

type CreateIssueResponse 

type CreateIssueResponse struct {
	ID   string `json:"id"`
	Key  string `json:"key"`
	Self string `json:"self"`
}

CreateIssueResponse represents the response from creating an issue.

type DeploymentType 

type DeploymentType string

DeploymentType represents the type of Jira deployment. 

const (
	DeploymentCloud      DeploymentType = "Cloud"
	DeploymentServer     DeploymentType = "Server"
	DeploymentDataCenter DeploymentType = "DataCenter"
)

Deployment types for Jira instances.

type HTTPConfig 

type HTTPConfig struct {
	// Timeout is the request timeout.
	Timeout time.Duration `mapstructure:"timeout"`

	// MaxIdleConns is the maximum number of idle connections.
	MaxIdleConns int `mapstructure:"max_idle_conns"`

	// IdleConnTimeout is how long to keep idle connections open.
	IdleConnTimeout time.Duration `mapstructure:"idle_conn_timeout"`
}

HTTPConfig holds HTTP client configuration.

type Issue 

type Issue struct {
	ID     string      `json:"id"`
	Key    string      `json:"key"`
	Self   string      `json:"self"`
	Fields IssueFields `json:"fields"`
}

Issue represents a Jira issue.

type IssueFields 

type IssueFields struct {
	Summary     string      `json:"summary"`
	Description any         `json:"description,omitempty"` // ADF (v3) or string (v2)
	Environment any         `json:"environment,omitempty"` // ADF (v3) or string (v2)
	Status      *Status     `json:"status,omitempty"`
	Priority    *Priority   `json:"priority,omitempty"`
	IssueType   *IssueType  `json:"issuetype,omitempty"`
	Project     *Project    `json:"project,omitempty"`
	Assignee    *User       `json:"assignee,omitempty"`
	Reporter    *User       `json:"reporter,omitempty"`
	Creator     *User       `json:"creator,omitempty"`
	Resolution  *Resolution `json:"resolution,omitempty"`
	Labels      []string    `json:"labels,omitempty"`
	Components  []Component `json:"components,omitempty"`
	FixVersions []Version   `json:"fixVersions,omitempty"`
	Created     string      `json:"created,omitempty"`
	Updated     string      `json:"updated,omitempty"`
	DueDate     string      `json:"duedate,omitempty"`

	// Custom fields are stored here with their field IDs as keys
	// e.g., "customfield_10001": 5.0 (story points)
	CustomFields map[string]any `json:"-"`

	// Parent for subtasks
	Parent *Issue `json:"parent,omitempty"`

	// Timetracking
	TimeTracking *TimeTracking `json:"timetracking,omitempty"`
}

IssueFields contains the fields of a Jira issue.

func (*IssueFields) CreatedTime 

func (f *IssueFields) CreatedTime() (time.Time, error)

CreatedTime parses and returns the Created timestamp.

func (*IssueFields) UpdatedTime 

func (f *IssueFields) UpdatedTime() (time.Time, error)

UpdatedTime parses and returns the Updated timestamp.

type IssueRef 

type IssueRef struct {
	Key string `json:"key,omitempty"`
	ID  string `json:"id,omitempty"`
}

IssueRef references an issue by key or ID.

type IssueType 

type IssueType struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Subtask     bool   `json:"subtask"`
	IconURL     string `json:"iconUrl,omitempty"`
	Self        string `json:"self,omitempty"`
}

IssueType represents an issue type in Jira.

type IssueTypeRef 

type IssueTypeRef struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
}

IssueTypeRef references an issue type by name or ID.

type Priority 

type Priority struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	IconURL string `json:"iconUrl,omitempty"`
	Self    string `json:"self,omitempty"`
}

Priority represents an issue priority.

type PriorityRef 

type PriorityRef struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
}

PriorityRef references a priority by name or ID.

type Project 

type Project struct {
	ID          string            `json:"id"`
	Key         string            `json:"key"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Self        string            `json:"self"`
	AvatarURLs  map[string]string `json:"avatarUrls,omitempty"`
}

Project represents a Jira project.

type ProjectRef 

type ProjectRef struct {
	Key string `json:"key,omitempty"`
	ID  string `json:"id,omitempty"`
}

ProjectRef references a project by key or ID.

type RateLimitConfig 

type RateLimitConfig struct {
	// MaxRetries is the maximum number of retry attempts.
	MaxRetries int `mapstructure:"max_retries"`

	// RetryWaitMin is the minimum wait between retries.
	RetryWaitMin time.Duration `mapstructure:"retry_wait_min"`

	// RetryWaitMax is the maximum wait between retries.
	RetryWaitMax time.Duration `mapstructure:"retry_wait_max"`

	// RetryJitter enables randomized jitter on retry waits.
	RetryJitter bool `mapstructure:"retry_jitter"`
}

RateLimitConfig holds rate limiting configuration. 

type RemoteLink struct {
	ID           int              `json:"id,omitempty"`
	Self         string           `json:"self,omitempty"`
	GlobalID     string           `json:"globalId,omitempty"`
	Application  *RemoteLinkApp   `json:"application,omitempty"`
	Relationship string           `json:"relationship,omitempty"`
	Object       RemoteLinkObject `json:"object"`
}

RemoteLink represents a remote link on an issue.

type RemoteLinkApp 

type RemoteLinkApp struct {
	Type string `json:"type,omitempty"`
	Name string `json:"name,omitempty"`
}

RemoteLinkApp represents the application information for a remote link.

type RemoteLinkIcon 

type RemoteLinkIcon struct {
	URL16x16 string `json:"url16x16,omitempty"`
	Title    string `json:"title,omitempty"`
}

RemoteLinkIcon represents the icon for a remote link.

type RemoteLinkObject 

type RemoteLinkObject struct {
	URL     string            `json:"url"`
	Title   string            `json:"title"`
	Summary string            `json:"summary,omitempty"`
	Icon    *RemoteLinkIcon   `json:"icon,omitempty"`
	Status  *RemoteLinkStatus `json:"status,omitempty"`
}

RemoteLinkObject represents the linked object details.

type RemoteLinkStatus 

type RemoteLinkStatus struct {
	Resolved bool            `json:"resolved"`
	Icon     *RemoteLinkIcon `json:"icon,omitempty"`
}

RemoteLinkStatus represents the status of a remote link.

type Resolution 

type Resolution struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Self        string `json:"self,omitempty"`
}

Resolution represents an issue resolution.

type RichTextConverter 

type RichTextConverter interface {
	// ToJira converts Markdown to the Jira format (ADF or Wiki Markup)
	ToJira(markdown string) (any, error)
	// FromJira converts from Jira format to Markdown
	FromJira(content any) (string, error)
}

RichTextConverter is an interface for converting rich text formats.

func NewRichTextConverter 

func NewRichTextConverter(deployment DeploymentType) RichTextConverter

NewRichTextConverter creates the appropriate converter based on deployment type.

type SearchOptions 

type SearchOptions struct {
	StartAt    int      `json:"startAt,omitempty"`
	MaxResults int      `json:"maxResults,omitempty"`
	Fields     []string `json:"fields,omitempty"`
	Expand     []string `json:"expand,omitempty"`
}

SearchOptions configures issue search.

type SearchResponse 

type SearchResponse struct {
	StartAt    int     `json:"startAt"`
	MaxResults int     `json:"maxResults"`
	Total      int     `json:"total"`
	Issues     []Issue `json:"issues"`
}

SearchResponse represents the response from the search endpoint.

type ServerConverter 

type ServerConverter struct {
	// contains filtered or unexported fields
}

ServerConverter implements RichTextConverter for Jira Server (Wiki Markup).

func NewServerConverter 

func NewServerConverter() *ServerConverter

NewServerConverter creates a converter for Jira Server/DC.

func (*ServerConverter) FromJira 

func (c *ServerConverter) FromJira(content any) (string, error)

FromJira converts Wiki Markup to Markdown.

func (*ServerConverter) ToJira 

func (c *ServerConverter) ToJira(markdown string) (any, error)

ToJira converts Markdown to Wiki Markup.

type ServerInfo 

type ServerInfo struct {
	BaseURL        string `json:"baseUrl"`
	Version        string `json:"version"`
	VersionNumbers []int  `json:"versionNumbers"`
	DeploymentType string `json:"deploymentType"` // "Cloud", "Server", "DataCenter"
	BuildNumber    int    `json:"buildNumber"`
	BuildDate      string `json:"buildDate"`
	ServerTime     string `json:"serverTime"`
	ScmInfo        string `json:"scmInfo,omitempty"` // Cloud only
	ServerTitle    string `json:"serverTitle"`
}

ServerInfo represents the response from /rest/api/X/serverInfo.

type Status 

type Status struct {
	ID             string         `json:"id"`
	Name           string         `json:"name"`
	Description    string         `json:"description,omitempty"`
	IconURL        string         `json:"iconUrl,omitempty"`
	StatusCategory StatusCategory `json:"statusCategory"`
	Self           string         `json:"self,omitempty"`
}

Status represents an issue status.

type StatusCategory 

type StatusCategory struct {
	ID        int    `json:"id"`
	Key       string `json:"key"` // "new", "indeterminate", "done"
	Name      string `json:"name"`
	ColorName string `json:"colorName,omitempty"`
	Self      string `json:"self,omitempty"`
}

StatusCategory represents a status category.

type TimeTracking 

type TimeTracking struct {
	OriginalEstimate         string `json:"originalEstimate,omitempty"`
	RemainingEstimate        string `json:"remainingEstimate,omitempty"`
	TimeSpent                string `json:"timeSpent,omitempty"`
	OriginalEstimateSeconds  int    `json:"originalEstimateSeconds,omitempty"`
	RemainingEstimateSeconds int    `json:"remainingEstimateSeconds,omitempty"`
	TimeSpentSeconds         int    `json:"timeSpentSeconds,omitempty"`
}

TimeTracking represents time tracking data.

type Transition 

type Transition struct {
	ID            string  `json:"id"`
	Name          string  `json:"name"`
	To            *Status `json:"to"`
	HasScreen     bool    `json:"hasScreen"`
	IsGlobal      bool    `json:"isGlobal"`
	IsInitial     bool    `json:"isInitial"`
	IsConditional bool    `json:"isConditional"`
}

Transition represents an available status transition.

type TransitionRef 

type TransitionRef struct {
	ID string `json:"id"`
}

TransitionRef references a transition by ID.

type TransitionRequest 

type TransitionRequest struct {
	Transition TransitionRef  `json:"transition"`
	Fields     map[string]any `json:"fields,omitempty"`
	Update     map[string]any `json:"update,omitempty"`
}

TransitionRequest represents a request to transition an issue.

type TransitionsResponse 

type TransitionsResponse struct {
	Transitions []Transition `json:"transitions"`
}

TransitionsResponse represents the response from the transitions endpoint.

type UpdateIssueRequest 

type UpdateIssueRequest struct {
	Fields map[string]any `json:"fields,omitempty"`
	Update map[string]any `json:"update,omitempty"`
}

UpdateIssueRequest represents a request to update issue fields.

type User 

type User struct {
	AccountID    string            `json:"accountId,omitempty"`    // Cloud (GDPR-compliant)
	Name         string            `json:"name,omitempty"`         // Server (username)
	Key          string            `json:"key,omitempty"`          // Server (user key)
	EmailAddress string            `json:"emailAddress,omitempty"` // May require scope
	DisplayName  string            `json:"displayName"`
	Active       bool              `json:"active"`
	TimeZone     string            `json:"timeZone,omitempty"`
	AvatarURLs   map[string]string `json:"avatarUrls,omitempty"`
	Self         string            `json:"self,omitempty"`
}

User represents a Jira user.

func (*User) GetID 

func (u *User) GetID() string

GetID returns the user identifier (accountId for Cloud, name for Server).

type UserRef 

type UserRef struct {
	AccountID string `json:"accountId,omitempty"` // Cloud
	Name      string `json:"name,omitempty"`      // Server
}

UserRef references a user by accountId (Cloud) or name (Server).

type Version 

type Version struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Archived    bool   `json:"archived"`
	Released    bool   `json:"released"`
	ReleaseDate string `json:"releaseDate,omitempty"`
	Self        string `json:"self,omitempty"`
}

Version represents a project version (fix version).

type VersionRef 

type VersionRef struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
}

VersionRef references a version by name or ID.

type WebhookEventType 

type WebhookEventType string

WebhookEventType represents a Jira webhook event type. 

const (
	WebhookEventIssueCreated   WebhookEventType = "jira:issue_created"
	WebhookEventIssueUpdated   WebhookEventType = "jira:issue_updated"
	WebhookEventIssueDeleted   WebhookEventType = "jira:issue_deleted"
	WebhookEventCommentCreated WebhookEventType = "comment_created"
	WebhookEventCommentUpdated WebhookEventType = "comment_updated"
	WebhookEventCommentDeleted WebhookEventType = "comment_deleted"
)

Webhook event types for Jira webhooks.

type WebhookPayload 

type WebhookPayload struct {
	Timestamp      int64            `json:"timestamp"`
	WebhookEvent   WebhookEventType `json:"webhookEvent"`
	IssueEventType string           `json:"issue_event_type_name,omitempty"`
	User           *User            `json:"user,omitempty"`
	Issue          *Issue           `json:"issue,omitempty"`
	Comment        *Comment         `json:"comment,omitempty"`
	Changelog      *Changelog       `json:"changelog,omitempty"`
}

WebhookPayload represents the common Jira webhook payload.

func ParseWebhookPayload 

func ParseWebhookPayload(body []byte) (*WebhookPayload, error)

ParseWebhookPayload parses a Jira webhook payload from JSON bytes.

func (*WebhookPayload) GetChangedFields 

func (p *WebhookPayload) GetChangedFields() []string

GetChangedFields returns the list of fields that changed in the webhook.

func (*WebhookPayload) GetFieldChange 

func (p *WebhookPayload) GetFieldChange(field string) *ChangelogItem

GetFieldChange returns the change details for a specific field.

func (*WebhookPayload) HasFieldChange 

func (p *WebhookPayload) HasFieldChange(field string) bool

HasFieldChange checks if a specific field changed in the webhook.

func (*WebhookPayload) IsAssigneeChange 

func (p *WebhookPayload) IsAssigneeChange() bool

IsAssigneeChange returns true if the issue assignee changed.

func (*WebhookPayload) IsPriorityChange 

func (p *WebhookPayload) IsPriorityChange() bool

IsPriorityChange returns true if the issue priority changed.

func (*WebhookPayload) IsStatusChange 

func (p *WebhookPayload) IsStatusChange() bool

IsStatusChange returns true if the issue status changed.

type WikiConverter 

type WikiConverter struct{}

WikiConverter handles conversion between Markdown and Jira Wiki Markup. This is used for Jira Server/Data Center API v2.

func NewWikiConverter 

func NewWikiConverter() *WikiConverter

NewWikiConverter creates a new Wiki Markup converter.

func (*WikiConverter) FromWiki 

func (c *WikiConverter) FromWiki(wiki string) string

FromWiki converts Jira Wiki Markup to Markdown.

func (*WikiConverter) ToWiki 

func (c *WikiConverter) ToWiki(markdown string) string

ToWiki converts Markdown to Jira Wiki Markup.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.