Go client library for Atlassian JIRA.

• 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.

• Go >= 1.8
• JIRA v6.3.4 & v7.1.2.

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

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.

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

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
}

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.

A more thorough, runnable example is provided in the examples directory. It's worth noting that using passwords in basic auth is now deprecated and will be removed. Jira gives you the ability to create tokens now.

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)
}

JIRA deprecated this authentication method. It's not longer available for use.

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.

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)
}

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

• andygrunwald/jitic - The JIRA Ticket Checker

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, 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.

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.

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

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