Go client library for Atlassian JIRA
Clone or download
Permalink
Failed to load latest commit information.
examples executable searchpages example Nov 18, 2018
img little bigger Apr 28, 2018
mocks added filter support for Jira issues Oct 8, 2018
.gitignore Add dep as a dependency manager Feb 17, 2018
.travis.yml TravisCI no longer works correctly with golang 1.6 and below Sep 12, 2018
Gopkg.lock Add dep as a dependency manager Feb 17, 2018
Gopkg.toml Add dep as a dependency manager Feb 17, 2018
LICENSE Initial commit Aug 20, 2015
Makefile Added Makefile Feb 28, 2017
README.md Fix error in the example code in README Nov 18, 2018
authentication.go Cleaning a bunch of go vet issues Mar 1, 2018
authentication_test.go go fmt and fixed some typos May 1, 2017
board.go Support state filter for GetAllSprints call Jun 11, 2018
board_test.go Support state filter for GetAllSprints call Jun 11, 2018
component.go Handle error with NewJiraError Jun 29, 2018
component_test.go Add ComponentService to allow creation of Components Jun 25, 2018
error.go Fixed null pointer when no response is received Nov 15, 2017
error_test.go Fixed null pointer when no response is received Nov 15, 2017
field.go doc: Fix comments Jun 25, 2018
field_test.go doc: Fix comments Jun 25, 2018
filter.go added missing Comment for filter.Get() Oct 8, 2018
filter_test.go added filter support for Jira issues Oct 8, 2018
group.go doc: Fix minor lint issues Jun 8, 2018
group_test.go move agile issue api to sprint, change name of GetByOption to GetWith… Apr 3, 2018
issue.go Merge pull request #177 from namely/master Oct 18, 2018
issue_test.go Add test for creation and subsequent retrieval of issue Oct 15, 2018
jira.go Instead of baking config into the client, adds a method call that all… Oct 17, 2018
jira_test.go Instead of baking config into the client, adds a method call that all… Oct 17, 2018
metaissue.go Fix GetQueryOptions in issue.go to use projectKeys instead of projectKey Mar 5, 2018
metaissue_test.go Added a GetCreateMetaWithOptions function, which extends the capabili… Mar 1, 2018
priority.go test: Add unit test for priority api Jun 12, 2018
priority_test.go test: Add unit test for priority api Jun 12, 2018
project.go Add new endpoint for getting assigned permission scheme for the project May 12, 2018
project_test.go Add positive test for project.GetPermissionScheme May 14, 2018
resolution.go feat: Add ResolutionService to retrieve resolutions Jun 25, 2018
resolution_test.go feat: Add ResolutionService to retrieve resolutions Jun 25, 2018
sprint.go doc: Fix minor lint issues Jun 8, 2018
sprint_test.go move agile issue api to sprint, change name of GetByOption to GetWith… Apr 3, 2018
statuscategory.go feat: Add StatusCategory GetList Jun 26, 2018
statuscategory_test.go feat: Add StatusCategory GetList Jun 26, 2018
user.go Add delete method for user Jul 11, 2018
user_test.go Add delete method for user Jul 11, 2018
version.go Manage versions startDate Oct 30, 2018
version_test.go Manage versions startDate Oct 30, 2018

README.md

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.

Compatible JIRA versions

This package was tested against JIRA v6.3.4 and v7.1.2.

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 mesos-slave@0.23 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.

Basic auth example

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

Authenticate with session cookie [DEPRECATED]

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

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

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

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 dep for dependency management. After cloning the repo, it's easy to make sure you have the correct dependencies by running dep ensure.

For adding new dependencies, updating dependencies, and other operations, the Daily Dep 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/.

License

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