Documentation ¶
Overview ¶
Package jira interacts with the Jira server. It requests v3 and v1 version of the Jira cloud API using Get and GetV1 methods.
See v3: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/, and v1: https://developer.atlassian.com/cloud/jira/software/rest/intro/
Index ¶
- Constants
- Variables
- type AuthType
- type Board
- type BoardResult
- type Client
- func (c *Client) AddIssueComment(key, comment string) error
- func (c *Client) AddIssueWorklog(key, started, timeSpent, comment, newEstimate string) error
- func (c *Client) AssignIssue(key, assignee string) error
- func (c *Client) AssignIssueV2(key, assignee string) error
- func (c *Client) BoardSearch(project, name string) (*BoardResult, error)
- func (c *Client) Boards(project, boardType string) (*BoardResult, error)
- func (c *Client) Create(req *CreateRequest) (*CreateResponse, error)
- func (c *Client) CreateV2(req *CreateRequest) (*CreateResponse, error)
- func (c *Client) DeleteIssue(key string, cascade bool) error
- func (c *Client) DeleteV2(ctx context.Context, path string, headers Header) (*http.Response, error)
- func (c *Client) Edit(key string, req *EditRequest) error
- func (c *Client) EpicIssues(key, jql string, from, limit uint) (*SearchResult, error)
- func (c *Client) EpicIssuesAdd(key string, issues ...string) error
- func (c *Client) EpicIssuesRemove(issues ...string) error
- func (c *Client) Get(ctx context.Context, path string, headers Header) (*http.Response, error)
- func (c *Client) GetCreateMeta(req *CreateMetaRequest) (*CreateMetaResponse, error)
- func (c *Client) GetCreateMetaForJiraServerV9(req *CreateMetaRequest) (*CreateMetaResponseJiraServerV9, error)
- func (c *Client) GetField() ([]*Field, error)
- func (c *Client) GetIssue(key string, opts ...filter.Filter) (*Issue, error)
- func (c *Client) GetIssueLinkTypes() ([]*IssueLinkType, error)
- func (c *Client) GetIssueV2(key string, opts ...filter.Filter) (*Issue, error)
- func (c *Client) GetLinkID(inwardIssue, outwardIssue string) (string, error)
- func (c *Client) GetV1(ctx context.Context, path string, headers Header) (*http.Response, error)
- func (c *Client) GetV2(ctx context.Context, path string, headers Header) (*http.Response, error)
- func (c *Client) LinkIssue(inwardIssue, outwardIssue, linkType string) error
- func (c *Client) Me() (*Me, error)
- func (c *Client) Post(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
- func (c *Client) PostV1(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
- func (c *Client) PostV2(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
- func (c *Client) Project() ([]*Project, error)
- func (c *Client) Put(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
- func (c *Client) PutV2(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
- func (c *Client) RemoteLinkIssue(issueID, title, url string) error
- func (c *Client) Search(jql string, from, limit uint) (*SearchResult, error)
- func (c *Client) SearchV2(jql string, from, limit uint) (*SearchResult, error)
- func (c *Client) ServerInfo() (*ServerInfo, error)
- func (c *Client) SprintIssues(sprintID int, jql string, from, limit uint) (*SearchResult, error)
- func (c *Client) SprintIssuesAdd(id string, issues ...string) error
- func (c *Client) Sprints(boardID int, qp string, from, limit int) (*SprintResult, error)
- func (c *Client) SprintsInBoards(boardIDs []int, qp string, limit int) []*Sprint
- func (c *Client) Transition(key string, data *TransitionRequest) (int, error)
- func (c *Client) Transitions(key string) ([]*Transition, error)
- func (c *Client) TransitionsV2(key string) ([]*Transition, error)
- func (c *Client) UnlinkIssue(linkID string) error
- func (c *Client) UserSearch(opt *UserSearchOptions) ([]*User, error)
- func (c *Client) UserSearchV2(opt *UserSearchOptions) ([]*User, error)
- func (c *Client) WatchIssue(key, watcher string) error
- func (c *Client) WatchIssueV2(key, watcher string) error
- type ClientFunc
- type Config
- type CreateMetaIssueType
- type CreateMetaRequest
- type CreateMetaResponse
- type CreateMetaResponseJiraServerV9
- type CreateRequest
- type CreateResponse
- type EditRequest
- type EditResponse
- type Epic
- type ErrMultipleFailed
- type ErrUnexpectedResponse
- type Errors
- type Field
- type Header
- type Issue
- type IssueFields
- type IssueLinkType
- type IssueType
- type IssueTypeField
- type MTLSConfig
- type Me
- type Project
- type SearchResult
- type ServerInfo
- type Sprint
- type SprintResult
- type Transition
- type TransitionRequest
- type TransitionRequestData
- type TransitionRequestFields
- type TransitionRequestUpdate
- type User
- type UserSearchOptions
Constants ¶
const ( // BoardTypeScrum represents a scrum board type. BoardTypeScrum = "scrum" // BoardTypeAll represents all board types. BoardTypeAll = "" )
const ( // RFC3339 is jira datetime format. RFC3339 = "2006-01-02T15:04:05-0700" // RFC3339MilliLayout is jira datetime format with milliseconds. RFC3339MilliLayout = "2006-01-02T15:04:05.000-0700" // InstallationTypeCloud represents Jira cloud server. InstallationTypeCloud = "Cloud" // InstallationTypeLocal represents on-premise Jira servers. InstallationTypeLocal = "Local" )
const ( // EpicFieldName represents epic name field in create metadata. EpicFieldName = "Epic Name" // EpicFieldLink represents epic link field in create metadata. EpicFieldLink = "Epic Link" )
const ( // IssueTypeEpic is an epic issue type. IssueTypeEpic = "Epic" // IssueTypeSubTask is a sub-task issue type. IssueTypeSubTask = "Sub-task" // AssigneeNone is an empty assignee. AssigneeNone = "none" // AssigneeDefault is a default assignee. AssigneeDefault = "default" )
const ( // ProjectTypeClassic is a classic project type. ProjectTypeClassic = "classic" // ProjectTypeNextGen is a next gen project type. ProjectTypeNextGen = "next-gen" )
const ( SprintStateActive = "active" SprintStateClosed = "closed" SprintStateFuture = "future" )
Sprint states.
Variables ¶
var ( // ErrNoResult denotes no results. ErrNoResult = fmt.Errorf("jira: no result") // ErrEmptyResponse denotes empty response from the server. ErrEmptyResponse = fmt.Errorf("jira: empty response from server") )
var ErrInvalidSearchOption = fmt.Errorf("invalid search option")
ErrInvalidSearchOption denotes invalid search option was given.
Functions ¶
This section is empty.
Types ¶
type AuthType ¶ added in v1.0.0
type AuthType string
AuthType is a jira authentication type. Currently supports basic and bearer (PAT). Defaults to basic for empty or invalid value.
type BoardResult ¶
type BoardResult struct { MaxResults int `json:"maxResults"` Total int `json:"total"` Boards []*Board `json:"values"` }
BoardResult holds response from /board endpoint.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a jira client.
func NewClient ¶
func NewClient(c Config, opts ...ClientFunc) *Client
NewClient instantiates new jira client.
func (*Client) AddIssueComment ¶
AddIssueComment adds comment to an issue using POST /issue/{key}/comment endpoint.
func (*Client) AddIssueWorklog ¶ added in v1.1.0
AddIssueWorklog adds worklog to an issue using POST /issue/{key}/worklog endpoint. Leave param `started` empty to use the server's current datetime as start date.
func (*Client) AssignIssue ¶
AssignIssue assigns issue to the user using v3 version of the PUT /issue/{key}/assignee endpoint.
func (*Client) AssignIssueV2 ¶ added in v0.1.0
AssignIssueV2 assigns issue to the user using v2 version of the PUT /issue/{key}/assignee endpoint.
func (*Client) BoardSearch ¶ added in v1.0.0
func (c *Client) BoardSearch(project, name string) (*BoardResult, error)
BoardSearch fetches boards with the given name in a project.
func (*Client) Boards ¶
func (c *Client) Boards(project, boardType string) (*BoardResult, error)
Boards gets all boards of a given type in a project.
func (*Client) Create ¶
func (c *Client) Create(req *CreateRequest) (*CreateResponse, error)
Create creates an issue using v3 version of the POST /issue endpoint.
func (*Client) CreateV2 ¶
func (c *Client) CreateV2(req *CreateRequest) (*CreateResponse, error)
CreateV2 creates an issue using v2 version of the POST /issue endpoint.
func (*Client) DeleteIssue ¶ added in v1.0.0
DeleteIssue deletes an issue using /issue/{key} endpoint.
func (*Client) DeleteV2 ¶ added in v1.0.0
DeleteV2 sends DELETE request to v2 version of the jira api.
func (*Client) Edit ¶
func (c *Client) Edit(key string, req *EditRequest) error
Edit updates an issue using POST /issue endpoint.
func (*Client) EpicIssues ¶
func (c *Client) EpicIssues(key, jql string, from, limit uint) (*SearchResult, error)
EpicIssues fetches issues in the given epic.
func (*Client) EpicIssuesAdd ¶
EpicIssuesAdd adds issues to an epic.
func (*Client) EpicIssuesRemove ¶
EpicIssuesRemove removes issues from epics.
func (*Client) GetCreateMeta ¶
func (c *Client) GetCreateMeta(req *CreateMetaRequest) (*CreateMetaResponse, error)
GetCreateMeta gets create metadata using GET /issue/createmeta endpoint.
func (*Client) GetCreateMetaForJiraServerV9 ¶ added in v1.2.0
func (c *Client) GetCreateMetaForJiraServerV9(req *CreateMetaRequest) (*CreateMetaResponseJiraServerV9, error)
GetCreateMetaForJiraServerV9 gets create metadata using GET /issue/createmeta endpoint for jira server 9 and above.
func (*Client) GetField ¶ added in v1.2.0
GetField gets all fields configured for a Jira instance using GET /field endpiont.
func (*Client) GetIssueLinkTypes ¶
func (c *Client) GetIssueLinkTypes() ([]*IssueLinkType, error)
GetIssueLinkTypes fetches issue link types using GET /issueLinkType endpoint.
func (*Client) GetIssueV2 ¶
GetIssueV2 fetches issue details using v2 version of Jira GET /issue/{key} endpoint.
func (*Client) LinkIssue ¶
LinkIssue connects issues to the given link type using POST /issueLink endpoint.
func (*Client) Post ¶
func (c *Client) Post(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
Post sends POST request to v3 version of the jira api.
func (*Client) PostV1 ¶
func (c *Client) PostV1(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
PostV1 sends POST request to v1 version of the jira api.
func (*Client) PostV2 ¶
func (c *Client) PostV2(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
PostV2 sends POST request to v2 version of the jira api.
func (*Client) Put ¶
func (c *Client) Put(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
Put sends PUT request to v3 version of the jira api.
func (*Client) PutV2 ¶
func (c *Client) PutV2(ctx context.Context, path string, body []byte, headers Header) (*http.Response, error)
PutV2 sends PUT request to v2 version of the jira api.
func (*Client) RemoteLinkIssue ¶ added in v1.2.0
RemoteLinkIssue adds a remote link to an issue using POST /issue/{issueId}/remotelink endpoint.
func (*Client) Search ¶
func (c *Client) Search(jql string, from, limit uint) (*SearchResult, error)
Search searches for issues using v3 version of the Jira GET /search endpoint.
func (*Client) SearchV2 ¶ added in v0.1.0
func (c *Client) SearchV2(jql string, from, limit uint) (*SearchResult, error)
SearchV2 searches an issues using v2 version of the Jira GET /search endpoint.
func (*Client) ServerInfo ¶ added in v1.2.0
func (c *Client) ServerInfo() (*ServerInfo, error)
ServerInfo fetches response from /serverInfo endpoint.
func (*Client) SprintIssues ¶
SprintIssues fetches issues in the given sprint.
func (*Client) SprintIssuesAdd ¶ added in v0.2.0
SprintIssuesAdd adds issues to the sprint.
func (*Client) Sprints ¶
Sprints fetches all sprints for a given board.
qp is an additional query parameters in key, value pair format, eg: state=closed.
func (*Client) SprintsInBoards ¶
SprintsInBoards fetches sprints across given board IDs.
qp is an additional query parameters in key, value pair format, eg: state=closed.
func (*Client) Transition ¶
func (c *Client) Transition(key string, data *TransitionRequest) (int, error)
Transition moves issue from one state to another using POST /issue/{key}/transitions endpoint.
func (*Client) Transitions ¶
func (c *Client) Transitions(key string) ([]*Transition, error)
Transitions fetches valid transitions for an issue using v3 version of the GET /issue/{key}/transitions endpoint.
func (*Client) TransitionsV2 ¶ added in v0.1.0
func (c *Client) TransitionsV2(key string) ([]*Transition, error)
TransitionsV2 fetches valid transitions for an issue using v2 version of the GET /issue/{key}/transitions endpoint.
func (*Client) UnlinkIssue ¶ added in v1.0.0
UnlinkIssue disconnects two issues using DELETE /issueLink/{linkId} endpoint.
func (*Client) UserSearch ¶
func (c *Client) UserSearch(opt *UserSearchOptions) ([]*User, error)
UserSearch search for user details using v3 version of the GET /user/assignable/search endpoint.
func (*Client) UserSearchV2 ¶ added in v0.1.0
func (c *Client) UserSearchV2(opt *UserSearchOptions) ([]*User, error)
UserSearchV2 search for user details using v2 version of the GET /user/assignable/search endpoint.
func (*Client) WatchIssue ¶ added in v1.4.0
WatchIssue adds user as a watcher using v2 version of the POST /issue/{key}/watchers endpoint.
func (*Client) WatchIssueV2 ¶ added in v1.4.0
WatchIssueV2 adds user as a watcher using using v2 version of the POST /issue/{key}/watchers endpoint.
type ClientFunc ¶
type ClientFunc func(*Client)
ClientFunc decorates option for client.
func WithInsecureTLS ¶ added in v1.0.0
func WithInsecureTLS(ins bool) ClientFunc
WithInsecureTLS is a functional opt that allow you to skip TLS certificate verification.
func WithTimeout ¶
func WithTimeout(to time.Duration) ClientFunc
WithTimeout is a functional opt to attach timeout to the client.
type Config ¶
type Config struct { Server string Login string APIToken string AuthType AuthType Insecure *bool Debug bool MTLSConfig MTLSConfig }
Config is a jira config.
type CreateMetaIssueType ¶
type CreateMetaIssueType struct { IssueType Fields map[string]IssueTypeField `json:"fields"` }
CreateMetaIssueType struct holds issue types from GET /issue/createmeta endpoint.
type CreateMetaRequest ¶
CreateMetaRequest struct holds request data for createmeta request.
type CreateMetaResponse ¶
type CreateMetaResponse struct { Projects []struct { Key string `json:"key"` Name string `json:"name"` IssueTypes []*CreateMetaIssueType `json:"issuetypes"` } `json:"projects"` }
CreateMetaResponse struct holds response from GET /issue/createmeta endpoint.
type CreateMetaResponseJiraServerV9 ¶ added in v1.2.0
type CreateMetaResponseJiraServerV9 struct { Values []struct { ID string `json:"id"` Name string `json:"name"` Subtask bool `json:"subtask"` } `json:"values"` }
CreateMetaResponseJiraServerV9 struct holds response from GET /issue/createmeta endpoint for jira server 9 and above.
type CreateRequest ¶
type CreateRequest struct { Project string Name string IssueType string // ParentIssueKey is required when creating a sub-task for classic project. // This can also be used to attach epic for next-gen project. ParentIssueKey string Summary string Body interface{} // string in v1/v2 and adf.ADF in v3 Reporter string Assignee string Priority string Labels []string Components []string FixVersions []string AffectsVersions []string // EpicField is the dynamic epic field name // that changes per jira installation. EpicField string // SubtaskField is usually called "Sub-task" but is // case-sensitive in Jira and can differ slightly // in different Jira versions. SubtaskField string // CustomFields holds all custom fields passed // while creating an issue. CustomFields map[string]string // contains filtered or unexported fields }
CreateRequest struct holds request data for create request.
func (*CreateRequest) ForInstallationType ¶ added in v1.3.0
func (cr *CreateRequest) ForInstallationType(it string)
ForInstallationType sets jira project type.
func (*CreateRequest) ForProjectType ¶ added in v0.2.0
func (cr *CreateRequest) ForProjectType(pt string)
ForProjectType sets jira project type.
func (*CreateRequest) WithCustomFields ¶ added in v1.3.0
func (cr *CreateRequest) WithCustomFields(cf []IssueTypeField)
WithCustomFields sets valid custom fields for the issue.
type CreateResponse ¶
CreateResponse struct holds response from POST /issue endpoint.
type EditRequest ¶
type EditRequest struct { IssueType string ParentIssueKey string Summary string Body string Priority string Labels []string Components []string FixVersions []string AffectsVersions []string // CustomFields holds all custom fields passed // while editing the issue. CustomFields map[string]string // contains filtered or unexported fields }
EditRequest struct holds request data for edit request. Setting an Assignee requires an account ID.
func (*EditRequest) WithCustomFields ¶ added in v1.3.0
func (er *EditRequest) WithCustomFields(cf []IssueTypeField)
WithCustomFields sets valid custom fields for the issue.
type EditResponse ¶
EditResponse struct holds response from POST /issue endpoint.
type ErrMultipleFailed ¶ added in v0.2.0
type ErrMultipleFailed struct {
Msg string
}
ErrMultipleFailed represents a grouped error, usually when multiple request fails when running them in a loop.
func (*ErrMultipleFailed) Error ¶ added in v0.2.0
func (e *ErrMultipleFailed) Error() string
type ErrUnexpectedResponse ¶
ErrUnexpectedResponse denotes response code other than the expected one.
func (*ErrUnexpectedResponse) Error ¶
func (e *ErrUnexpectedResponse) Error() string
type Field ¶ added in v1.2.0
type Field struct { ID string `json:"id"` Name string `json:"name"` Custom bool `json:"custom"` Schema struct { DataType string `json:"type"` Items string `json:"items,omitempty"` FieldID int `json:"customId,omitempty"` } `json:"schema"` }
Field holds field info.
type Issue ¶
type Issue struct { Key string `json:"key"` Fields IssueFields `json:"fields"` }
Issue holds issue info.
type IssueFields ¶
type IssueFields struct { Summary string `json:"summary"` Description interface{} `json:"description"` // string in v1/v2, adf.ADF in v3 Labels []string `json:"labels"` Resolution struct { Name string `json:"name"` } `json:"resolution"` IssueType IssueType `json:"issueType"` Parent *struct { Key string `json:"key"` } `json:"parent,omitempty"` Assignee struct { Name string `json:"displayName"` } `json:"assignee"` Priority struct { Name string `json:"name"` } `json:"priority"` Reporter struct { Name string `json:"displayName"` } `json:"reporter"` Watches struct { IsWatching bool `json:"isWatching"` WatchCount int `json:"watchCount"` } `json:"watches"` Status struct { Name string `json:"name"` } `json:"status"` Components []struct { Name string `json:"name"` } `json:"components"` FixVersions []struct { Name string `json:"name"` } `json:"fixVersions"` AffectsVersions []struct { Name string `json:"name"` } `json:"versions"` Comment struct { Comments []struct { ID string `json:"id"` Author User `json:"author"` Body interface{} `json:"body"` // string in v1/v2, adf.ADF in v3 Created string `json:"created"` } `json:"comments"` Total int `json:"total"` } `json:"comment"` Subtasks []Issue IssueLinks []struct { ID string `json:"id"` LinkType struct { Name string `json:"name"` Inward string `json:"inward"` Outward string `json:"outward"` } `json:"type"` InwardIssue *Issue `json:"inwardIssue,omitempty"` OutwardIssue *Issue `json:"outwardIssue,omitempty"` } `json:"issueLinks"` Created string `json:"created"` Updated string `json:"updated"` }
IssueFields holds issue fields.
type IssueLinkType ¶
type IssueLinkType struct { ID string `json:"id"` Name string `json:"name"` Inward string `json:"inward"` Outward string `json:"outward"` }
IssueLinkType holds issue link type info.
type IssueType ¶
type IssueType struct { ID string `json:"id"` Name string `json:"name"` Handle string `json:"untranslatedName,omitempty"` // This field may not exist in older version of the API. Subtask bool `json:"subtask"` }
IssueType holds issue type info.
type IssueTypeField ¶ added in v1.0.0
type IssueTypeField struct { Name string `json:"name"` Key string `json:"key"` Schema struct { DataType string `json:"type"` Items string `json:"items,omitempty"` } `json:"schema"` FieldID string `json:"fieldId,omitempty"` }
IssueTypeField holds issue field info.
type MTLSConfig ¶ added in v1.5.0
MTLSConfig is MTLS authtype specific config.
type Me ¶
type Me struct { Login string `json:"name"` Name string `json:"displayName"` Email string `json:"emailAddress"` Timezone string `json:"timeZone"` }
Me struct holds response from /myself endpoint.
type Project ¶
type Project struct { Key string `json:"key"` Name string `json:"name"` Lead struct { Name string `json:"displayName"` } `json:"lead"` Type string `json:"style"` }
Project holds project info.
type SearchResult ¶
type SearchResult struct { StartAt int `json:"startAt"` MaxResults int `json:"maxResults"` Total int `json:"total"` Issues []*Issue `json:"issues"` }
SearchResult struct holds response from /search endpoint.
type ServerInfo ¶ added in v1.2.0
type ServerInfo struct { Version string `json:"version"` VersionNumbers []int `json:"versionNumbers"` DeploymentType string `json:"deploymentType"` BuildNumber int `json:"buildNumber"` DefaultLocale struct { Locale string `json:"locale"` } `json:"defaultLocale"` }
ServerInfo struct holds response from /serverInfo endpoint.
type Sprint ¶
type Sprint struct { ID int `json:"id"` Name string `json:"name"` Status string `json:"state"` StartDate string `json:"startDate"` EndDate string `json:"endDate"` CompleteDate string `json:"completeDate,omitempty"` BoardID int `json:"originBoardId,omitempty"` }
Sprint holds sprint info.
type SprintResult ¶
type SprintResult struct { MaxResults int `json:"maxResults"` StartAt int `json:"startAt"` IsLast bool `json:"isLast"` Sprints []*Sprint `json:"values"` }
SprintResult holds response from /board/{boardID}/sprint endpoint.
type Transition ¶
type Transition struct { ID json.Number `json:"id"` Name string `json:"name"` IsAvailable bool `json:"isAvailable"` }
Transition holds issue transition info.
type TransitionRequest ¶
type TransitionRequest struct { Update *TransitionRequestUpdate `json:"update,omitempty"` Fields *TransitionRequestFields `json:"fields,omitempty"` Transition *TransitionRequestData `json:"transition"` }
TransitionRequest struct holds request data for issue transition request.
type TransitionRequestData ¶
TransitionRequestData is a transition request data.
type TransitionRequestFields ¶ added in v1.2.0
type TransitionRequestFields struct { Assignee *struct { Name string `json:"name"` } `json:"assignee,omitempty"` Resolution *struct { Name string `json:"name"` } `json:"resolution,omitempty"` }
TransitionRequestFields struct holds a list of issue screen fields to update along with sub-fields.
type TransitionRequestUpdate ¶ added in v1.2.0
type TransitionRequestUpdate struct { Comment []struct { Add struct { Body string `json:"body"` } `json:"add"` } `json:"comment,omitempty"` }
TransitionRequestUpdate struct holds a list of operations to perform on the issue screen field.