Go client library for Atlassian Jira

go-jira

GoDoc Build Status Go Report Card

Go client library for Atlassian Jira.

Go client library for Atlassian Jira

Features

  • Authentication (HTTP Basic, OAuth, Session Cookie)
  • Create and retrieve issues
  • Create and retrieve issue transitions (status updates)
  • Call every API endpoint of the Jira, even if it is not directly implemented in this library

This package is not Jira API complete (yet), but you can call every API endpoint you want. See Call a not implemented API endpoint how to do this. For all possible API endpoints of Jira have a look at latest Jira REST API documentation.

Requirements

  • Go >= 1.14
  • Jira v6.3.4 & v7.1.2.

Note that we also run our tests against 1.13, though only the last two versions of Go are officially supported.

Installation

It is go gettable

go get github.com/andygrunwald/go-jira

For stable versions you can use one of our tags with gopkg.in. E.g.

package main

import (
	jira "gopkg.in/andygrunwald/go-jira.v1"
)
...

(optional) to run unit / example tests:

cd $GOPATH/src/github.com/andygrunwald/go-jira
go test -v ./...

API

Please have a look at the GoDoc documentation for a detailed API description.

The latest Jira REST API documentation was the base document for this package.

Examples

Further a few examples how the API can be used. A few more examples are available in the GoDoc examples section.

Get a single issue

Lets retrieve MESOS-3325 from the Apache Mesos project.

package main

import (
	"fmt"
	"github.com/andygrunwald/go-jira"
)

func main() {
	jiraClient, _ := jira.NewClient(nil, "https://issues.apache.org/jira/")
	issue, _, _ := jiraClient.Issue.Get("MESOS-3325", nil)

	fmt.Printf("%s: %+v\n", issue.Key, issue.Fields.Summary)
	fmt.Printf("Type: %s\n", issue.Fields.Type.Name)
	fmt.Printf("Priority: %s\n", issue.Fields.Priority.Name)

	// MESOS-3325: Running [email protected] in a container causes slave to be lost after a restart
	// Type: Bug
	// Priority: Critical
}

Authentication

The go-jira library does not handle most authentication directly. Instead, authentication should be handled within an http.Client. That client can then be passed into the NewClient function when creating a jira client.

For convenience, capability for basic and cookie-based authentication is included in the main library.

Token (Jira on Atlassian Cloud)

Token-based authentication uses the basic authentication scheme, with a user-generated API token in place of a user's password. You can generate a token for your user here. Additional information about Atlassian Cloud API tokens can be found here.

A more thorough, runnable example is provided in the examples directory.

func main() {
	tp := jira.BasicAuthTransport{
		Username: "username",
		Password: "token",
	}

	client, err := jira.NewClient(tp.Client(), "https://my.jira.com")

	u, _, err := client.User.Get("some_user")

	fmt.Printf("\nEmail: %v\nSuccess!\n", u.EmailAddress)
}

Basic (self-hosted Jira)

Password-based API authentication works for self-hosted Jira only, and has been deprecated for users of Atlassian Cloud.

The above token authentication example may be used, substituting a user's password for a generated token.

Authenticate with OAuth

If you want to connect via OAuth to your Jira Cloud instance checkout the example of using OAuth authentication with Jira in Go by @Lupus.

For more details have a look at the issue #56.

Create an issue

Example how to create an issue.

package main

import (
	"fmt"
	"github.com/andygrunwald/go-jira"
)

func main() {
	base := "https://my.jira.com"
	tp := jira.BasicAuthTransport{
		Username: "username",
		Password: "token",
	}

	jiraClient, err := jira.NewClient(tp.Client(), base)
	if err != nil {
		panic(err)
	}

	i := jira.Issue{
		Fields: &jira.IssueFields{
			Assignee: &jira.User{
				Name: "myuser",
			},
			Reporter: &jira.User{
				Name: "youruser",
			},
			Description: "Test Issue",
			Type: jira.IssueType{
				Name: "Bug",
			},
			Project: jira.Project{
				Key: "PROJ1",
			},
			Summary: "Just a demo issue",
		},
	}
	issue, _, err := jiraClient.Issue.Create(&i)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s: %+v\n", issue.Key, issue.Fields.Summary)
}

Change an issue status

This is how one can change an issue status. In this example, we change the issue from "To Do" to "In Progress."

package main

import (
	"fmt"
	"github.com/andygrunwald/go-jira"
)

func main() {
	base := "https://my.jira.com"
	tp := jira.BasicAuthTransport{
		Username: "username",
		Password: "token",
	}

	jiraClient, err := jira.NewClient(tp.Client(), base)
	if err != nil {
		panic(err)
	}

	issue, _, _ := jiraClient.Issue.Get("FART-1", nil)
	currentStatus := issue.Fields.Status.Name
	fmt.Printf("Current status: %s\n", currentStatus)

	var transitionID string
	possibleTransitions, _, _ := jiraClient.Issue.GetTransitions("FART-1")
	for _, v := range possibleTransitions {
		if v.Name == "In Progress" {
			transitionID = v.ID
			break
		}
	}

	jiraClient.Issue.DoTransition("FART-1", transitionID)
	issue, _, _ = jiraClient.Issue.Get(testIssueID, nil)
	fmt.Printf("Status after transition: %+v\n", issue.Fields.Status.Name)
}

Call a not implemented API endpoint

Not all API endpoints of the Jira API are implemented into go-jira. But you can call them anyway: Lets get all public projects of Atlassian`s Jira instance.

package main

import (
	"fmt"
	"github.com/andygrunwald/go-jira"
)

func main() {
	base := "https://my.jira.com"
	tp := jira.BasicAuthTransport{
		Username: "username",
		Password: "token",
	}

	jiraClient, err := jira.NewClient(tp.Client(), base)
	req, _ := jiraClient.NewRequest("GET", "rest/api/2/project", nil)

	projects := new([]jira.Project)
	_, err = jiraClient.Do(req, projects)
	if err != nil {
		panic(err)
	}

	for _, project := range *projects {
		fmt.Printf("%s: %s\n", project.Key, project.Name)
	}

	// ...
	// BAM: Bamboo
	// BAMJ: Bamboo Jira Plugin
	// CLOV: Clover
	// CONF: Confluence
	// ...
}

Implementations

Code structure

The code structure of this package was inspired by google/go-github.

There is one main part (the client). Based on this main client the other endpoints, like Issues or Authentication are extracted in services. E.g. IssueService or AuthenticationService. These services own a responsibility of the single endpoints / usecases of Jira.

Contribution

We ❤️ PR's

Contribution, in any kind of way, is highly welcome! It doesn't matter if you are not able to write code. Creating issues or holding talks and help other people to use go-jira is contribution, too! A few examples:

  • Correct typos in the README / documentation
  • Reporting bugs
  • Implement a new feature or endpoint
  • Sharing the love of go-jira and help people to get use to it

If you are new to pull requests, checkout Collaborating on projects using issues and pull requests / Creating a pull request.

Dependency management

go-jira uses go modules for dependency management. After cloning the repo, it's easy to make sure you have the correct dependencies by running go mod tidy.

For adding new dependencies, updating dependencies, and other operations, the Daily workflow is a good place to start.

Sandbox environment for testing

Jira offers sandbox test environments at http://go.atlassian.com/cloud-dev.

You can read more about them at https://developer.atlassian.com/blog/2016/04/cloud-ecosystem-dev-env/.

Releasing

Install standard-version

npm i -g standard-version
standard-version
git push --tags

Manually copy/paste text from changelog (for this new version) into the release on Github.com. E.g.

https://github.com/andygrunwald/go-jira/releases/edit/v1.11.0

License

This project is released under the terms of the MIT license.

Owner
Comments
  • support for oauth2 used by Jira Add-Ons

    support for oauth2 used by Jira Add-Ons

    In order to support REST API calls from Jira Add-Ons created through the Atlassian Connect framework, we need to:

    1. create a JSON Web Token (JWT) assertion
    2. use the JWT assertion + secret to get an access token
    3. include the access token in the request headers

    I've got a working standalone example and I'll create a PR in a bit.

  • How to create an issue with watchers added

    How to create an issue with watchers added

    I am wondering how I can create an issue with given watchers. That is my code

    	var issueWatcher []*jira.Watcher
    	for _, w := range data.Watchers {
    		var watcher = &jira.Watcher{
    			Name: w,
    		}
    		issueWatcher = append(issueWatcher, watcher)
    	}
    
    	var issueWatches = jira.Watches{
    		Watchers: issueWatcher,
    	}
    
    	var issue = jira.Issue{
    		Fields: &jira.IssueFields{
    			Assignee:    &jira.User{Name: data.Assignee},
    			Reporter:    &jira.User{Name: data.Reporter},
    			Project:     jira.Project{Key: data.Project},
    			Summary:     data.Summary,
    			Description: data.Description,
    			Type:        jira.IssueType{Name: data.IssueType},
    			Watches:     &issueWatches,
    		},
    	}
    

    But I get following error:

    Error: Issue could not created: Request failed. Please analyze the request body for more details. Status code: 400
    

    Could you provide an example?

  • Unable to create an issue in jira using this API

    Unable to create an issue in jira using this API

    we are currently using the Jira v7.3.6 server. While using the API I was able to connect to the server and also able to retrieve the projects as well in the Jira application. But I was unable to create an issue and getting the error message as page not found(Screenshot is attached) image Can someone help me out to resolve this ? or is this API supported for only the jira version mentioned in the requirements ?

  • Add support for context package

    Add support for context package

    The PR changes the API go-jira adding support for "context" package. This will enable golang applications coordinate cancellation accross many different goroutines.

    PR breaks backwards compatibility (added ctx context.Context as first parameter to all methods), so maybe it should be part of next major release.

  • Documentation for custom jira fields

    Documentation for custom jira fields

    Hi!

    First: thanks for your work here! Its nice to have a Jira API impl. in Go!

    I stumbled upon the Unknowns struct field of IssueFields and thus I think it should be possible (?) to add custom Jira fields - but how? Can you provide an example?

    Thanks, pH-T

  • Add Transition and Sprint API handling

    Add Transition and Sprint API handling

    Added TransitionService with 2 methods:

    • GetList for retrieving possible transitions for an issue
    • Create for creating transition and changing issue status in the process

    This is just very basic functionality, the API itself has more features, but I wanted to have bare minimum. It can be expanded.

    Docs for API used: https://docs.atlassian.com/jira/REST/latest/#api/2/issue-getTransitions https://docs.atlassian.com/jira/REST/latest/#api/2/issue-doTransition

    fixes #21

  • This library needs a large lizard logo

    This library needs a large lizard logo

    The name of library is go-jira. Godzilla in japanese reads Gojira (based on this article and sound file: https://en.wikipedia.org/wiki/Godzilla https://upload.wikimedia.org/wikipedia/commons/d/d0/Ja-Godzilla.oga ).

    The issue title is obvious, if this library ever has a logo, it should be a large lizard (maybe with gopher face?). Pic related: http://cliparts.co/cliparts/ki8/nxa/ki8nxab5T.png

  • Basic auth support

    Basic auth support

    Hey,

    I am relatively new to go but as I understand your library suppose to support basic auth connection with Jira. Your documentation for session cookie authentication even recommends to use basic auth. But I do not see any place to provide username and password to this library. I looked into go documentation but they say I would need to provide a username and password for each request object so I can't even set it globally on the http connection that I could pass in.

    Can some one please advice?

  • x509: certificate signed by unknown authority

    x509: certificate signed by unknown authority

    Hi, I'm getting below error from calling jiraClient.Authentication.AcquireSessionCookie. Do I need certificate? panic: Auth at JIRA instance failed (HTTP(S) request). Post https://myjira.com/rest/auth/1/session: x509: certificate signed by unknown authority

  • feat: add support for JWT auth with qsh needed by add-ons

    feat: add support for JWT auth with qsh needed by add-ons

    Adding support for auth using JWT's created with QSH fields and signed with a shared secret exchanged during Add-On installation. All other officially supported Atlassian clients have support for this and we found it useful in our environment.

    Read more here: https://developer.atlassian.com/cloud/jira/platform/understanding-jwt

    Also, added the go.sum file per the best practices.

  • add Sprint column for issue. Fix get group member function to return all members.

    add Sprint column for issue. Fix get group member function to return all members.

    • Change api use of Issue.Get from https://developer.atlassian.com/cloud/jira/platform/rest/#api-api-2-issue-issueIdOrKey-get to https://docs.atlassian.com/jira-software/REST/7.3.1/#agile/1.0/issue-getIssue in order to export Sprint column
    • Fix related test cases
    • Export IsLast and NextPage for cases that members' length is more than one page. Call Group.Get to iterate through all members instead of returning only the first page (we have no way to exam if there's other pages of members from this api design, so return all by default)
  • chore(deps): bump github.com/golang-jwt/jwt/v4 from 4.4.1 to 4.4.2

    chore(deps): bump github.com/golang-jwt/jwt/v4 from 4.4.1 to 4.4.2

    Bumps github.com/golang-jwt/jwt/v4 from 4.4.1 to 4.4.2.

    Release notes

    Sourced from github.com/golang-jwt/jwt/v4's releases.

    v4.4.2

    What's Changed

    New Contributors

    Full Changelog: https://github.com/golang-jwt/jwt/compare/v4.4.1...v4.4.2

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
  • feat: Add sprint goal

    feat: Add sprint goal

    Description

    Adds the optional Goal field to the Sprint Struct

    Example:

    // Example code
    sprints, _, _ := jiraClient.Board.GetAllSprints(boardID)
    fmt.Println(sprints[0].Goal)
    

    Checklist

  • Add Search (POST) support.

    Add Search (POST) support.

    This adds support for the POST search endpoint for long queries on Jira. The client interface does not change; the request to the server will be upgraded to a POST request behind the scenes if the URL would be more than 2000 characters long.

  • refactor: Replaced github.com/pkg/errors with errors

    refactor: Replaced github.com/pkg/errors with errors

    Description

    Please describe what does this Pull Request fix or add?.

    It replaces the obsolete module github.com/pkg/errors with the official one errors which got introduced in golang 1.13

    Information that is useful here:

    • The What: What is your change doing?
    • The Why: Why is your change useful/needed? What is your use case? (this helps us to understand the real world better)
    • Type of change: Things like Bugfix, New feature, Code quality improvements, Dependency upgrade, Documentation, ...

    Code quality improvements

    • Breaking change: Yes or no? Backward compatible?

    No

    • Related to an issue: Does this fix or close an issue? Or is related in any kind?
    • #200
    • Jira Version + Type: Which Jira version and type (on-premise / cloud) you have used?

    Cloud

    Example:

    Let us know how users can use or test this functionality.

    // Example code
    
    

    Checklist

  • BREAKING CHANGE: Use create request body instead of custom parameters

    BREAKING CHANGE: Use create request body instead of custom parameters

    Description

    Please describe what does this Pull Request fix or add?.

    atm the use of custom fields is impossible, because the value could only be a string, so a field with type option-with-child which requires a { "value": "foo" } as value wont work. By allowing such change, the struct needed to changed so it would be a breaking change anyway. While doing that i also removed all parameters which are a "part" of the struct and put them together.

    Information that is useful here:

    • The What: What is your change doing?

    Allowing to transfer more complex custom field values

    • The Why: Why is your change useful/needed? What is your use case? (this helps us to understand the real world better)

    Currently only the value string can be used, but more complex structure is needed to for custom fields. And the request struct type which was given is not the same which is mentioned in the jira docs, so i changed the field structure to match it again.

    • Type of change: Things like Bugfix, New feature, Code quality improvements, Dependency upgrade, Documentation, ...

    New feature Code quality improvements

    • Breaking change: Yes or no? Backward compatible?

    Yes, no backward compatibility

    • Related to an issue: Does this fix or close an issue? Or is related in any kind?

    Not directly, maybe:

    • #417
    • #380
    • Jira Version + Type: Which Jira version and type (on-premise / cloud) you have used?

    Cloud

    Example:

    Let us know how users can use or test this functionality.

    // Example code
    
    

    Checklist

  • Added requesttype

    Added requesttype

    Description

    For our current implementation against jira we decided to use this module, but it lacks some requests we need which we would like to contribute in this and upcoming pull requests. This PR will only focus on the Requesttype. I noticed that there is currently a PagedDTO struct which contains []ìnterface{} for values. To improve the handing i decided to support this new Requesttype for only golang 1.18+ and use a new struct PagedDTOT which is a generic version of the normal one PagedDTO.

    Information that is useful here:

    • The What: What is your change doing?

    Adds support for non experimental requesttype using serviceDeskID https://developer.atlassian.com/cloud/jira/service-desk/rest/api-group-requesttype/

    • The Why: Why is your change useful/needed? What is your use case? (this helps us to understand the real world better)

    Currently there is no support for that in this module

    • Type of change: Things like Bugfix, New feature, Code quality improvements, Dependency upgrade, Documentation, ...

    Bugfix New feature Code quality improvements

    • Breaking change: Yes or no? Backward compatible?

    No breaking change

    • Related to an issue: Does this fix or close an issue? Or is related in any kind?

    Nope

    • Jira Version + Type: Which Jira version and type (on-premise / cloud) you have used?

    Example:

    Let us know how users can use or test this functionality.

    // Example code
    
    jiraClient, err := jira.NewClient(nil, "jiraurl")
    if err != nil {
      return err
    }
    
    pager, _, err := jiraClient.RequestType.GetWithContext(ctx, 1)
    if err != nil {
      return err
    }
    
    fmt.Println(pager.Size)
    
    for _, v := range pager.Values {
      fmt.Println(v.Name)
    
      fmt.Println(v.Icon.Links.IconURLs)
    }
    

    Checklist

A Go client implementing a client-side distributed consumer group client for Amazon Kinesis.
A Go client implementing a client-side distributed consumer group client for Amazon Kinesis.

Kinesumer is a Go client implementing a client-side distributed consumer group client for Amazon Kinesis.

May 12, 2022
Clusterpedia-client - clusterpedia-client supports the use of native client-go mode to call the clusterpedia API

clusterpedia-client supports the use of native client-go mode to call the cluste

Jan 7, 2022
Client-go - Clusterpedia-client supports the use of native client-go mode to call the clusterpedia API

clusterpedia-client supports the use of native client-go mode to call the cluste

Jun 17, 2022
Aoe4-client - Client library for aoe4 leaderboards etc

AOE4 Client Overview This is a go client used to query AOE4 data from either the

Jan 18, 2022
Client for the cloud-iso-client

cloud-iso-client Client for the cloud-iso-client. Register an API token Before using this client library, you need to register an API token under your

Dec 6, 2021
Go-http-client: An enhanced http client for Golang
Go-http-client: An enhanced http client for Golang

go-http-client An enhanced http client for Golang Documentation on go.dev ?? This package provides you a http client package for your http requests. Y

May 23, 2022
Nutanix-client-go - Go client for the Nutanix Prism V3 API

nutanix-client-go This repository contains portions of the Nutanix API client code in nutanix/terraform-provider-nutanix. It has been extracted to red

Jan 6, 2022
Balabola-go-client - GO client for Yandex balabola service

Balabola GO Client GO client for Yandex balabola service Yandex warning The neur

Jan 29, 2022
Client-server-golang-sqs - Client Server with SQS and golang

Client Server with SQS and golang Multi-threaded client-server demo with Go What

Feb 14, 2022
Go Client Library for Amazon Product Advertising API

go-amazon-product-advertising-api Go Client Library for Amazon Product Advertising API How to Use go get -u github.com/ngs/go-amazon-product-advertisi

Jun 27, 2022
A Go client library for the Twitter 1.1 API

Anaconda Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API. Successful API queries return native Go structs th

Jun 15, 2022
Go(lang) client library for Cachet (open source status page system).

cachet Go(lang) client library for Cachet (open source status page system). Features Full API support Components Incidents Metrics Subscribers Various

Jan 28, 2022
Go client library for interacting with Coinpaprika's API

Coinpaprika API Go Client Usage This library provides convenient way to use coinpaprika.com API in Go. Coinpaprika delivers full market data to the wo

Jun 12, 2022
Package githubv4 is a client library for accessing GitHub GraphQL API v4 (https://developer.github.com/v4/).

githubv4 Package githubv4 is a client library for accessing GitHub GraphQL API v4 (https://docs.github.com/en/graphql). If you're looking for a client

Jun 23, 2022
a Go (Golang) MusicBrainz WS2 client library - work in progress
a Go (Golang) MusicBrainz WS2 client library - work in progress

gomusicbrainz a Go (Golang) MusicBrainz WS2 client library - a work in progress. Current state Currently GoMusicBrainz provides methods to perform sea

May 3, 2022
This project implements a Go client library for the Hipchat API.

Hipchat This project implements a Go client library for the Hipchat API (API version 2 is not supported). Pull requests are welcome as the API is limi

Jan 12, 2022
Go(lang) client library for accessing information of an Apache Mesos cluster.

megos Go(lang) client library for accessing an Apache Mesos cluster. Features Determine the Mesos leader Get the current state of every mesos node (ma

Jul 18, 2021
Client library for UptimeRobot v2 API

uptimerobot uptimerobot is a Go library and command-line client for the Uptime Robot website monitoring service. It allows you to search for existing

Jul 1, 2022
May 25, 2021