1
0
mirror of https://github.com/interviewstreet/go-jira.git synced 2024-12-12 10:13:40 +02:00
go-jira/README.md

172 lines
5.4 KiB
Markdown
Raw Normal View History

2015-09-03 12:25:03 +02:00
# go-jira
[![GoDoc](https://godoc.org/github.com/andygrunwald/go-jira?status.svg)](https://godoc.org/github.com/andygrunwald/go-jira)
[![Build Status](https://travis-ci.org/andygrunwald/go-jira.svg?branch=master)](https://travis-ci.org/andygrunwald/go-jira)
2016-03-26 22:38:23 +02:00
[![Go Report Card](https://goreportcard.com/badge/github.com/andygrunwald/go-jira)](https://goreportcard.com/report/github.com/andygrunwald/go-jira)
2016-03-27 14:21:27 +02:00
[![Coverage Status](https://coveralls.io/repos/github/andygrunwald/go-jira/badge.svg?branch=master)](https://coveralls.io/github/andygrunwald/go-jira?branch=master)
2016-03-26 22:43:30 +02:00
2015-09-03 12:48:16 +02:00
[Go](https://golang.org/) client library for [Atlassian JIRA](https://www.atlassian.com/software/jira).
2015-09-03 12:25:03 +02:00
2015-09-03 12:48:16 +02:00
![Go client library for Atlassian JIRA](./img/go-jira-compressed.png "Go client library for Atlassian JIRA.")
2015-09-03 12:25:03 +02:00
## Features
2015-09-03 12:58:01 +02:00
* Authentication (HTTP Basic, OAuth, Session Cookie)
* Create and receive issues
* Create and retrieve issue transitions (status updates)
2016-03-27 13:02:25 +02:00
* Call every API endpoint of the JIRA, even it is not directly implemented in this library
2016-03-27 13:04:31 +02:00
This package is not JIRA API complete (yet), but you can call every API endpoint you want. See [Call a not implemented API endpoint](#call-a-not-implemented-api-endpoint) how to do this. For all possible API endpoints of JRIA have a look at [latest JIRA REST API documentation](https://docs.atlassian.com/jira/REST/latest/).
2015-09-03 12:58:01 +02:00
2016-03-27 13:02:25 +02:00
## Compatible JIRA versions
This package was tested against JIRA v6.3.4 and v7.1.2.
2015-09-03 12:25:03 +02:00
## Installation
It is go gettable
$ go get github.com/andygrunwald/go-jira
(optional) to run unit / example tests:
$ cd $GOPATH/src/github.com/andygrunwald/go-jira
2016-03-27 13:02:25 +02:00
$ go test -v ./...
2015-09-03 12:25:03 +02:00
## API
Please have a look at the [GoDoc documentation](https://godoc.org/github.com/andygrunwald/go-jira) for a detailed API description.
2015-09-03 12:48:16 +02:00
The [latest JIRA REST API documentation](https://docs.atlassian.com/jira/REST/latest/) was the base document for this package.
2015-09-03 12:25:03 +02:00
## Examples
Further a few examples how the API can be used.
A few more examples are available in the [GoDoc examples section](https://godoc.org/github.com/andygrunwald/go-jira#pkg-examples).
2015-09-03 13:35:48 +02:00
### Get a single issue
Lets retrieve [MESOS-3325](https://issues.apache.org/jira/browse/MESOS-3325) from the [Apache Mesos](http://mesos.apache.org/) project.
```go
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")
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
}
```
2015-09-03 12:25:03 +02:00
### Authenticate with session cookie
2016-05-28 19:25:51 +02:00
Some actions require an authenticated user.
Here is an example with a session cookie authentification.
```go
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")
if err != nil {
panic(err)
}
fmt.Printf("%s: %+v\n", issue.Key, issue.Fields.Summary)
}
```
2015-09-03 12:58:01 +02:00
### Call a not implemented API endpoint
2016-05-28 19:25:51 +02:00
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](https://jira.atlassian.com/).
```go
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
// ...
}
```
2015-09-03 12:58:01 +02:00
2015-09-03 12:25:03 +02:00
## Implementations
2015-09-03 17:15:43 +02:00
* [andygrunwald/jitic](https://github.com/andygrunwald/jitic) - The JIRA Ticket Checker
2015-09-03 12:25:03 +02:00
2016-03-27 13:02:25 +02:00
## Code structure
The code structure of this package was inspired by [google/go-github](https://github.com/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](https://github.com/andygrunwald/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](https://github.com/andygrunwald/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](https://help.github.com/articles/creating-a-pull-request/).
2015-09-03 12:25:03 +02:00
## License
This project is released under the terms of the [MIT license](http://en.wikipedia.org/wiki/MIT_License).