Help us shape the future of Go! Take the 2026 Go Developer Survey

jira

package
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: May 5, 2025 License: GPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package jira contains the Jira bridge implementation

Index

Constants

View Source 
const TimeFormat = "2006-01-02T15:04:05.999999999Z0700"

Variables

View Source 
var (
	ErrMissingCredentials = errors.New("missing credentials")
)

Functions

func ParseTime 

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

ParseTime parse an RFC3339 string with nanoseconds

func UpdateIssueStatus 

func UpdateIssueStatus(client *Client, issueKeyOrID string, desiredStateNameOrID string) (time.Time, error)

UpdateIssueStatus attempts to change the "status" field by finding a transition which achieves the desired state and then performing that transition

Types

type ChangeLogEntry 

type ChangeLogEntry struct {
	ID      string          `json:"id"`
	Author  User            `json:"author"`
	Created Time            `json:"created"`
	Items   []ChangeLogItem `json:"items"`
}

ChangeLogEntry One entry in a changelog https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type ChangeLogItem 

type ChangeLogItem struct {
	Field      string `json:"field"`
	FieldType  string `json:"fieldtype"`
	From       string `json:"from"`
	FromString string `json:"fromString"`
	To         string `json:"to"`
	ToString   string `json:"toString"`
}

ChangeLogItem "field-change" data within a changelog entry. A single changelog entry might effect multiple fields. For example, closing an issue generally requires a change in "status" and "resolution" https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type ChangeLogIterator 

type ChangeLogIterator struct {
	Err error
	// contains filtered or unexported fields
}

ChangeLogIterator cursor within paginated results from the /search endpoint

func (*ChangeLogIterator) HasError 

func (cli *ChangeLogIterator) HasError() bool

HasError returns true if the iterator is holding an error

func (*ChangeLogIterator) HasNext 

func (cli *ChangeLogIterator) HasNext() bool

HasNext returns true if there is another item available in the result set

func (*ChangeLogIterator) Next 

func (cli *ChangeLogIterator) Next() *ChangeLogEntry

Next Return the next item in the result set and advance the iterator. Advancing the iterator may require fetching a new page.

type ChangeLogPage 

type ChangeLogPage struct {
	StartAt    int              `json:"startAt"`
	MaxResults int              `json:"maxResults"`
	Total      int              `json:"total"`
	IsLast     bool             `json:"isLast"` // Cloud-only
	Entries    []ChangeLogEntry `json:"histories"`
	Values     []ChangeLogEntry `json:"values"`
}

ChangeLogPage A collection of changes to issue metadata https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

func (*ChangeLogPage) IsLastPage 

func (clp *ChangeLogPage) IsLastPage() bool

IsLastPage return true if there are no more items beyond this page

func (*ChangeLogPage) NextStartAt 

func (clp *ChangeLogPage) NextStartAt() int

NextStartAt return the index of the first item on the next page

type Client 

type Client struct {
	*http.Client
	// contains filtered or unexported fields
}

Client Thin wrapper around the http.Client providing jira-specific methods for API endpoints

func NewClient 

func NewClient(ctx context.Context, serverURL string) *Client

NewClient Construct a new client connected to the provided server and utilizing the given context for asynchronous events

func (*Client) AddComment 

func (client *Client) AddComment(issueKeyOrID, body string) (*Comment, error)

AddComment adds a new comment to an issue (and returns it).

func (*Client) CreateIssue 

func (client *Client) CreateIssue(projectIDOrKey, title, body string,
	extra map[string]interface{}) (*IssueCreateResult, error)

CreateIssue creates a new JIRA issue and returns it

func (*Client) DoTransition 

func (client *Client) DoTransition(issueKeyOrID string, transitionID string) (time.Time, error)

DoTransition changes the "status" of an issue

func (*Client) GetChangeLog 

func (client *Client) GetChangeLog(idOrKey string, maxResults int, startAt int) (*ChangeLogPage, error)

GetChangeLog fetch one page of the changelog for an issue via the /issue/{IssueIdOrKey}/changelog endpoint (for JIRA cloud) or /issue/{IssueIdOrKey} with (fields=*none&expand=changelog) (for JIRA server) https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue

func (*Client) GetComments 

func (client *Client) GetComments(idOrKey string, maxResults int, startAt int) (*CommentPage, error)

GetComments returns a page of comments via the issue/{IssueIdOrKey}/comment endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getComment

func (*Client) GetIssue 

func (client *Client) GetIssue(idOrKey string, fields []string, expand []string,
	properties []string) (*Issue, error)

GetIssue fetches an issue object via the /issue/{IssueIdOrKey} endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue

func (*Client) GetProject 

func (client *Client) GetProject(projectIDOrKey string) (*Project, error)

GetProject returns the project JSON object given its id or key

func (*Client) GetServerInfo 

func (client *Client) GetServerInfo() (*ServerInfo, error)

GetServerInfo Fetch server information from the /serverinfo endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue

func (*Client) GetServerTime 

func (client *Client) GetServerTime() (Time, error)

GetServerTime returns the current time on the server

func (*Client) GetTransitions 

func (client *Client) GetTransitions(issueKeyOrID string) (*TransitionList, error)

GetTransitions returns a list of available transitions for an issue

func (*Client) IterChangeLog 

func (client *Client) IterChangeLog(idOrKey string, pageSize int) *ChangeLogIterator

IterChangeLog returns an iterator over entries in the changelog for an issue

func (*Client) IterComments 

func (client *Client) IterComments(idOrKey string, pageSize int) *CommentIterator

IterComments returns an iterator over paginated comments within an issue

func (*Client) IterSearch 

func (client *Client) IterSearch(jql string, pageSize int) *SearchIterator

IterSearch return an iterator over paginated results for a JQL search

func (*Client) Login 

func (client *Client) Login(credType, login, password string) error

Login POST credentials to the /session endpoint and get a session cookie

func (*Client) RefreshSessionToken 

func (client *Client) RefreshSessionToken(username, password string) error

RefreshSessionToken formulate the JSON request object from the user credentials and POST it to the /session endpoint and get a session cookie

func (*Client) RefreshSessionTokenRaw 

func (client *Client) RefreshSessionTokenRaw(credentialsJSON []byte) error

RefreshSessionTokenRaw POST credentials to the /session endpoint and get a session cookie

func (*Client) Search 

func (client *Client) Search(jql string, maxResults int, startAt int) (*SearchResult, error)

Search Perform an issue a JQL search on the /search endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/search

func (*Client) SetTokenCredentials 

func (client *Client) SetTokenCredentials(username, password string) error

SetTokenCredentials POST credentials to the /session endpoint and get a session cookie

func (*Client) UpdateComment 

func (client *Client) UpdateComment(issueKeyOrID, commentID, body string) (
	*Comment, error)

UpdateComment changes the text of a comment

func (*Client) UpdateIssueBody 

func (client *Client) UpdateIssueBody(issueKeyOrID, body string) (time.Time, error)

UpdateIssueBody changes the "description" field of a JIRA issue

func (*Client) UpdateIssueTitle 

func (client *Client) UpdateIssueTitle(issueKeyOrID, title string) (time.Time, error)

UpdateIssueTitle changes the "summary" field of a JIRA issue

func (*Client) UpdateLabels 

func (client *Client) UpdateLabels(issueKeyOrID string, added, removed []common.Label) (time.Time, error)

UpdateLabels changes labels for an issue

type ClientTransport 

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

ClientTransport wraps http.RoundTripper by adding a "Content-Type=application/json" header

func (*ClientTransport) RoundTrip 

func (ct *ClientTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip overrides the default by adding the content-type header

func (*ClientTransport) SetCredentials 

func (ct *ClientTransport) SetCredentials(username string, token string)

type Comment 

type Comment struct {
	ID           string `json:"id"`
	Body         string `json:"body"`
	Author       User   `json:"author"`
	UpdateAuthor User   `json:"updateAuthor"`
	Created      Time   `json:"created"`
	Updated      Time   `json:"updated"`
}

Comment the JSON object for a single comment item returned in a list of comments https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getComments

type CommentCreate 

type CommentCreate struct {
	Body string `json:"body"`
}

CommentCreate the JSOn object that is POSTed to the /comment endpoint to create a new comment

type CommentIterator 

type CommentIterator struct {
	Err error
	// contains filtered or unexported fields
}

CommentIterator cursor within paginated results from the /comment endpoint

func (*CommentIterator) HasError 

func (ci *CommentIterator) HasError() bool

HasError returns true if the iterator is holding an error

func (*CommentIterator) HasNext 

func (ci *CommentIterator) HasNext() bool

HasNext returns true if there is another item available in the result set

func (*CommentIterator) Next 

func (ci *CommentIterator) Next() *Comment

Next Return the next item in the result set and advance the iterator. Advancing the iterator may require fetching a new page.

type CommentPage 

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

CommentPage the JSON object holding a single page of comments returned either by direct query or within an issue query https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getComments

func (*CommentPage) IsLastPage 

func (cp *CommentPage) IsLastPage() bool

IsLastPage return true if there are no more items beyond this page

func (*CommentPage) NextStartAt 

func (cp *CommentPage) NextStartAt() int

NextStartAt return the index of the first item on the next page

type Issue 

type Issue struct {
	ID        string        `json:"id"`
	Key       string        `json:"key"`
	Fields    IssueFields   `json:"fields"`
	ChangeLog ChangeLogPage `json:"changelog"`
}

Issue Top-level object for an issue https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type IssueCreate 

type IssueCreate struct {
	Fields IssueCreateFields `json:"fields"`
}

IssueCreate the JSON object that is POSTed to the /issue endpoint to create a new issue

type IssueCreateFields 

type IssueCreateFields struct {
	Project     Project   `json:"project"`
	Summary     string    `json:"summary"`
	Description string    `json:"description"`
	IssueType   IssueType `json:"issuetype"`
}

IssueCreateFields fields that are included in an IssueCreate request

type IssueCreateResult 

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

IssueCreateResult the JSON object returned after issue creation.

type IssueFields 

type IssueFields struct {
	Creator     User        `json:"creator"`
	Created     Time        `json:"created"`
	Description string      `json:"description"`
	Summary     string      `json:"summary"`
	Comments    CommentPage `json:"comment"`
	Labels      []string    `json:"labels"`
}

IssueFields the JSON object returned as the "fields" member of an issue. There are a very large number of fields and many of them are custom. We only grab a few that we need. https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/issue-getIssue

type IssueType 

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

IssueType the JSON object representing an issue type (i.e. "bug", "task") Note that we don't use all the fields so we have only implemented a couple.

type Jira 

type Jira struct{}

Jira Main object for the bridge

func (*Jira) Configure 

func (j *Jira) Configure(repo *cache.RepoCache, params core.BridgeParams, interactive bool) (core.Configuration, error)

Configure sets up the bridge configuration

func (*Jira) LoginMetaKey 

func (*Jira) LoginMetaKey() string

func (*Jira) NewExporter 

func (*Jira) NewExporter() core.Exporter

NewExporter returns the jira exporter

func (*Jira) NewImporter 

func (*Jira) NewImporter() core.Importer

NewImporter returns the jira importer

func (*Jira) Target 

func (*Jira) Target() string

Target returns "jira"

func (*Jira) ValidParams 

func (*Jira) ValidParams() map[string]interface{}

func (*Jira) ValidateConfig 

func (*Jira) ValidateConfig(conf core.Configuration) error

ValidateConfig returns true if all required keys are present

type Project 

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

Project the JSON object representing a project. Note that we don't use all the fields so we have only implemented a couple.

type SearchIterator 

type SearchIterator struct {
	Err error
	// contains filtered or unexported fields
}

SearchIterator cursor within paginated results from the /search endpoint

func (*SearchIterator) HasError 

func (si *SearchIterator) HasError() bool

HasError returns true if the iterator is holding an error

func (*SearchIterator) HasNext 

func (si *SearchIterator) HasNext() bool

HasNext returns true if there is another item available in the result set

func (*SearchIterator) Next 

func (si *SearchIterator) Next() *Issue

Next Return the next item in the result set and advance the iterator. Advancing the iterator may require fetching a new page.

type SearchRequest 

type SearchRequest struct {
	JQL        string   `json:"jql"`
	StartAt    int      `json:"startAt"`
	MaxResults int      `json:"maxResults"`
	Fields     []string `json:"fields"`
}

SearchRequest the JSON object POSTed to the /search endpoint

type SearchResult 

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

SearchResult The result type from querying the search endpoint https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/search

func (*SearchResult) IsLastPage 

func (sr *SearchResult) IsLastPage() bool

IsLastPage return true if there are no more items beyond this page

func (*SearchResult) NextStartAt 

func (sr *SearchResult) NextStartAt() int

NextStartAt return the index of the first item on the next page

type ServerInfo 

type ServerInfo struct {
	BaseURL          string `json:"baseUrl"`
	Version          string `json:"version"`
	VersionNumbers   []int  `json:"versionNumbers"`
	BuildNumber      int    `json:"buildNumber"`
	BuildDate        Time   `json:"buildDate"`
	ServerTime       Time   `json:"serverTime"`
	ScmInfo          string `json:"scmInfo"`
	BuildPartnerName string `json:"buildPartnerName"`
	ServerTitle      string `json:"serverTitle"`
}

ServerInfo general server information returned by the /serverInfo endpoint. Notably `ServerTime` will tell you the time on the server.

type Session 

type Session struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

Session credential cookie name/value pair received after logging in and required to be sent on all subsequent requests

type SessionQuery 

type SessionQuery struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

SessionQuery the JSON object that is POSTed to the /session endpoint in order to login and get a session cookie

type SessionResponse 

type SessionResponse struct {
	Session Session `json:"session"`
}

SessionResponse the JSON object returned from a /session query (login)

type Status 

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

Status the JSON object representing a status (i.e. "Open", "Closed")

type StatusCategory 

type StatusCategory struct {
	ID        int    `json:"id"`
	Key       string `json:"key"`
	Self      string `json:"self"`
	ColorName string `json:"colorName"`
	Name      string `json:"name"`
}

StatusCategory the JSON object representing a status category

type Time 

type Time struct {
	time.Time
}

Time is just a time.Time with a JSON serialization

func (*Time) UnmarshalJSON 

func (t *Time) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON parses an RFC3339 date string into a time object borrowed from: https://stackoverflow.com/a/39180230/141023

type Transition 

type Transition struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	To   Status `json:"to"`
}

Transition the JSON object represenging a transition from one Status to another Status in a JIRA workflow

type TransitionList 

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

TransitionList the JSON object returned from the /transitions endpoint

type User 

type User struct {
	DisplayName  string `json:"displayName"`
	EmailAddress string `json:"emailAddress"`
	Key          string `json:"key"`
	Name         string `json:"name"`
}

User the JSON object representing a JIRA user https://docs.atlassian.com/software/jira/docs/api/REST/8.2.6/#api/2/user

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.