jira

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Jan 2, 2023 License: MIT Imports: 16 Imported by: 0

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

View Source 
const (
	// BoardTypeScrum represents a scrum board type.
	BoardTypeScrum = "scrum"
	// BoardTypeAll represents all board types.
	BoardTypeAll = ""
)
View Source 
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"
)
View Source 
const (
	// EpicFieldName represents epic name field in create metadata.
	EpicFieldName = "Epic Name"
	// EpicFieldLink represents epic link field in create metadata.
	EpicFieldLink = "Epic Link"
)
View Source 
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"
)
View Source 
const (
	// ProjectTypeClassic is a classic project type.
	ProjectTypeClassic = "classic"
	// ProjectTypeNextGen is a next gen project type.
	ProjectTypeNextGen = "next-gen"
)
View Source 
const (
	SprintStateActive = "active"
	SprintStateClosed = "closed"
	SprintStateFuture = "future"
)

Sprint states.

Variables

View Source 
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")
)
View Source 
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. 

const (
	// AuthTypeBasic is a basic auth.
	AuthTypeBasic AuthType = "basic"
	// AuthTypeBearer is a bearer auth.
	AuthTypeBearer AuthType = "bearer"
)

func (AuthType) String added in v1.0.0 

func (at AuthType) String() string

String implements stringer interface.

type Board 

type Board struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Type string `json:"type"`
}

Board holds board info.

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 

func (c *Client) AddIssueComment(key, comment string) error

AddIssueComment adds comment to an issue using POST /issue/{key}/comment endpoint.

func (*Client) AddIssueWorklog added in v1.1.0 

func (c *Client) AddIssueWorklog(key, started, timeSpent, comment string) error

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 

func (c *Client) AssignIssue(key, assignee string) error

AssignIssue assigns issue to the user using v3 version of the PUT /issue/{key}/assignee endpoint.

func (*Client) AssignIssueV2 added in v0.1.0 

func (c *Client) AssignIssueV2(key, assignee string) error

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 

func (c *Client) DeleteIssue(key string, cascade bool) error

DeleteIssue deletes an issue using /issue/{key} endpoint.

func (*Client) DeleteV2 added in v1.0.0 

func (c *Client) DeleteV2(ctx context.Context, path string, headers Header) (*http.Response, error)

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 

func (c *Client) EpicIssuesAdd(key string, issues ...string) error

EpicIssuesAdd adds issues to an epic.

func (*Client) EpicIssuesRemove 

func (c *Client) EpicIssuesRemove(issues ...string) error

EpicIssuesRemove removes issues from epics.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, headers Header) (*http.Response, error)

Get sends GET request to v3 version of the jira api.

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 

func (c *Client) GetField() ([]*Field, error)

GetField gets all fields configured for a Jira instance using GET /field endpiont.

func (*Client) GetIssue 

func (c *Client) GetIssue(key string, opts ...filter.Filter) (*Issue, error)

GetIssue fetches issue details using GET /issue/{key} endpoint.

func (*Client) GetIssueLinkTypes 

func (c *Client) GetIssueLinkTypes() ([]*IssueLinkType, error)

GetIssueLinkTypes fetches issue link types using GET /issueLinkType endpoint.

func (*Client) GetIssueV2 

func (c *Client) GetIssueV2(key string, opts ...filter.Filter) (*Issue, error)

GetIssueV2 fetches issue details using v2 version of Jira GET /issue/{key} endpoint.

func (*Client) GetLinkID added in v1.0.0 

func (c *Client) GetLinkID(inwardIssue, outwardIssue string) (string, error)

GetLinkID gets linkID between two issues.

func (*Client) GetV1 

func (c *Client) GetV1(ctx context.Context, path string, headers Header) (*http.Response, error)

GetV1 sends get request to v1 version of the jira api.

func (*Client) GetV2 

func (c *Client) GetV2(ctx context.Context, path string, headers Header) (*http.Response, error)

GetV2 sends GET request to v2 version of the jira api.

func (*Client) LinkIssue 

func (c *Client) LinkIssue(inwardIssue, outwardIssue, linkType string) error

LinkIssue connects issues to the given link type using POST /issueLink endpoint.

func (*Client) Me 

func (c *Client) Me() (*Me, error)

Me fetches response from /myself 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) Project 

func (c *Client) Project() ([]*Project, error)

Project fetches response from /project endpoint.

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 

func (c *Client) RemoteLinkIssue(issueID, title, url string) error

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 

func (c *Client) SprintIssues(sprintID int, jql string, from, limit uint) (*SearchResult, error)

SprintIssues fetches issues in the given sprint.

func (*Client) SprintIssuesAdd added in v0.2.0 

func (c *Client) SprintIssuesAdd(id string, issues ...string) error

SprintIssuesAdd adds issues to the sprint.

func (*Client) Sprints 

func (c *Client) Sprints(boardID int, qp string, from, limit int) (*SprintResult, error)

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 

func (c *Client) SprintsInBoards(boardIDs []int, qp string, limit int) []*Sprint

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 

func (c *Client) UnlinkIssue(linkID string) error

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.

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
}

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 

type CreateMetaRequest struct {
	Projects       string
	IssueTypeNames string
	Expand         string
}

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
	// 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 

type CreateResponse struct {
	ID  string `json:"id"`
	Key string `json:"key"`
}

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
	// 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 

type EditResponse struct {
	ID  string `json:"id"`
	Key string `json:"key"`
}

EditResponse struct holds response from POST /issue endpoint.

type Epic 

type Epic struct {
	Name string `json:"name"`
	Link string `json:"link"`
}

Epic holds epic info.

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 

type ErrUnexpectedResponse struct {
	Body       Errors
	Status     string
	StatusCode int
}

ErrUnexpectedResponse denotes response code other than the expected one.

func (*ErrUnexpectedResponse) Error 

func (e *ErrUnexpectedResponse) Error() string

type Errors 

type Errors struct {
	Errors          map[string]string
	ErrorMessages   []string
	WarningMessages []string
}

Errors is a jira error type.

func (Errors) String 

func (e Errors) String() 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 Header map[string]string

Header is a key, value pair for request headers.

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"`
	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 Me 

type Me struct {
	Login string `json:"name"`
	Name  string `json:"displayName"`
	Email string `json:"emailAddress"`
}

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 

type TransitionRequestData struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

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.

type User 

type User struct {
	AccountID   string `json:"accountId,omitempty"`
	Email       string `json:"emailAddress"`
	Name        string `json:"name,omitempty"`
	DisplayName string `json:"displayName"`
	Active      bool   `json:"active"`
}

User holds user info.

type UserSearchOptions 

type UserSearchOptions struct {
	Project    string
	Query      string
	Username   string
	AccountID  string
	StartAt    int
	MaxResults int
}

UserSearchOptions holds options to search for user.

Source Files

View all Source files

Directories

Path Synopsis
Package filter provides a way to pass optional parameters to client methods.
 Package filter provides a way to pass optional parameters to client methods.
issue

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.