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.