1
0
mirror of https://github.com/interviewstreet/go-jira.git synced 2025-01-03 22:52:17 +02:00
Go to file
2018-02-24 11:52:57 -08:00
examples/basicauth Add an example for basic auth 2018-02-24 11:52:57 -08:00
img Added project logo 2015-09-03 12:48:16 +02:00
mocks Add the ability to get all issues in a sprint 2016-07-26 16:18:58 -04:00
.gitignore Add dep as a dependency manager 2018-02-17 11:14:47 -08:00
.travis.yml Added Golang 1.9 to TravisCI 2017-08-31 15:56:29 +02:00
authentication_test.go go fmt and fixed some typos 2017-05-01 14:59:27 +02:00
authentication.go go fmt and docs 2017-05-01 15:06:18 +02:00
board_test.go Moved Board-Functionality to BoardService and renamed Sprint function according to the API 2016-07-17 11:17:29 +02:00
board.go Merge branch 'master' into rbriski/jira_error 2017-11-03 15:24:23 -07:00
error_test.go Fixed null pointer when no response is received 2017-11-14 17:57:26 -08:00
error.go Fixed null pointer when no response is received 2017-11-14 17:57:26 -08:00
example_test.go Add GoDoc examples 2017-10-28 11:51:53 -04:00
Gopkg.lock Add dep as a dependency manager 2018-02-17 11:14:47 -08:00
Gopkg.toml Add dep as a dependency manager 2018-02-17 11:14:47 -08:00
group_test.go Add tests for group apis 2017-11-29 16:10:42 +09:00
group.go Add tests for group apis 2017-11-29 16:10:42 +09:00
issue_test.go Added method & tests for logging time against an issue 2018-02-17 12:09:23 +00:00
issue.go Merge pull request #107 from robiball/add_worklog_methods 2018-02-21 21:39:36 +01:00
jira_test.go Adding basic auth and accompanying tests 2018-02-24 11:27:46 -08:00
jira.go Adding basic auth and accompanying tests 2018-02-24 11:27:46 -08:00
LICENSE Initial commit 2015-08-20 17:02:46 +02:00
Makefile Added Makefile 2017-02-28 10:02:05 +01:00
metaissue_test.go Fixed typos 2017-05-01 15:03:03 +02:00
metaissue.go Fixed typos 2017-05-01 15:03:03 +02:00
project_test.go adds ability to list projects with query params 2018-01-31 10:34:47 -05:00
project.go add IssueTypes field to ProjectList 2018-01-31 11:25:35 -05:00
README.md Add info about sandbox environment 2018-02-24 11:29:55 -08:00
sprint_test.go go fmt 2016-07-29 19:45:03 +02:00
sprint.go Adding jira.Error to all functions that can return a jira specific JSON error 2017-11-03 15:22:32 -07:00
user_test.go Merge branch 'master' of https://github.com/manute/go-jira into manute-master 2017-12-10 19:54:09 +01:00
user.go Applied NewJiraError for user api endpoints 2017-12-10 19:56:03 +01:00
version_test.go add basic Version endpoints 2018-01-22 11:34:41 +01:00
version.go add basic Version endpoints 2018-01-22 11:34:41 +01:00

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
}

Authenticate with jira

Some actions require an authenticated user.

Authenticate with basic auth

Here is an example with basic auth authentication.

package main

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

func main() {
	jiraClient, err := jira.NewClient(nil, "https://your.jira-instance.com/")
	if err != nil {
		panic(err)
	}
	jiraClient.Authentication.SetBasicAuth("username", "password")

	issue, _, err := jiraClient.Issue.Get("SYS-5156", nil)
	if err != nil {
		panic(err)
	}

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

Here is an example with session cookie authentication.

package main

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

func main() {
	jiraClient, err := jira.NewClient(nil, "https://your.jira-instance.com/")
	if err != nil {
		panic(err)
	}

	res, err := jiraClient.Authentication.AcquireSessionCookie("username", "password")
	if err != nil || res == false {
		fmt.Printf("Result: %v\n", res)
		panic(err)
	}

	issue, _, err := jiraClient.Issue.Get("SYS-5156", nil)
	if err != nil {
		panic(err)
	}

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

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() {
	jiraClient, err := jira.NewClient(nil, "https://your.jira-instance.com/")
	if err != nil {
		panic(err)
	}

	res, err := jiraClient.Authentication.AcquireSessionCookie("username", "password")
	if err != nil || res == false {
		fmt.Printf("Result: %v\n", res)
		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() {
	jiraClient, _ := jira.NewClient(nil, "https://jira.atlassian.com/")
	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 if 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.