Git 中文文档

go-jira


Build Status

Go client library for Atlassian Jira.

Go client library for Atlassian Jira

⚠️ State of this library ⚠️


v2 of this library is in development.v2 will contain breaking changes ⚠️The current main branch can contains the development version of v2.

The goals of v2 are:

idiomatic go usage
proper documentation
being compliant with different kinds of Atlassian Jira products (on-premise vs. cloud)
remove flaws introduced during the early times of this library

See our milestone Road to v2 and provide feedback in Development is kicking: Road to v2 🚀 #489. Attention: The current main branch represents the v2 development version - we treat this version as unstable and breaking changes are expected.

If you want to stay more stable, please use v1.*- See our releases. Latest stable release: v1.16.0

Features


Authentication (HTTP Basic, OAuth, Session Cookie, Bearer (for PATs))
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

  1. ``` shell
  2. go get github.com/andygrunwald/go-jira
  3. ```

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.

  1. ``` go
  2. package main

  4. import (
  5. "fmt"
  6. jira "github.com/andygrunwald/go-jira"
  7. )

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

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

  17. // MESOS-3325: Running mesos-slave@0.23 in a container causes slave to be lost after a restart
  18. // Type: Bug
  19. // Priority: Critical
  20. }
  21. ```

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.

  1. ``` go
  2. func main() {
  3. tp := jira.BasicAuthTransport{
  4.   Username: "<username>",
  5.   APIToken: "<api-token>",
  6. }

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

  10. u, _, err = client.User.GetCurrentUser(context.Background())

  12. fmt.Printf("Email: %v\n", u.EmailAddress)
  13. fmt.Println("Success!")
  14. }
  15. ```

Bearer - Personal Access Tokens (self-hosted Jira)


For self-hosted Jira(v8.14 and later), Personal Access Tokens (PATs) were introduced. Similar to the API tokens, PATs are a safe alternative to using username and password for authentication with scripts and integrations. PATs use the Bearer authentication scheme. Read more about Jira PATs here.

See examples/bearerauth for how to use the Bearer authentication scheme with Jira in Go.

Basic (self-hosted Jira)


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

Depending on your version of Jira, either of the above token authentication examples 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.

  1. ``` go
  2. package main

  4. import (
  5. "fmt"
  6. "github.com/andygrunwald/go-jira"
  7. )

  9. func main() {
  10. base := "https://my.jira.com"
  11. tp := jira.BasicAuthTransport{
  12.   Username: "username",
  13.   Password: "token",
  14. }

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

  21. i := jira.Issue{
  22.   Fields: &jira.IssueFields{
  23.    Assignee: &jira.User{
  24.     Name: "myuser",
  25.    },
  26.    Reporter: &jira.User{
  27.     Name: "youruser",
  28.    },
  29.    Description: "Test Issue",
  30.    Type: jira.IssueType{
  31.     Name: "Bug",
  32.    },
  33.    Project: jira.Project{
  34.     Key: "PROJ1",
  35.    },
  36.    Summary: "Just a demo issue",
  37.   },
  38. }
  39. issue, _, err := jiraClient.Issue.Create(&i)
  40. if err != nil {
  41.   panic(err)
  42. }

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

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

  1. ``` go
  2. package main

  4. import (
  5. "fmt"
  6. "github.com/andygrunwald/go-jira"
  7. )

  9. func main() {
  10.         testIssueID := "FART-1"
  11. base := "https://my.jira.com"
  12. tp := jira.BasicAuthTransport{
  13.   Username: "username",
  14.   Password: "token",
  15. }

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

  22. issue, _, _ := jiraClient.Issue.Get(testIssueID, nil)
  23. currentStatus := issue.Fields.Status.Name
  24. fmt.Printf("Current status: %s\n", currentStatus)

  26. var transitionID string
  27. possibleTransitions, _, _ := jiraClient.Issue.GetTransitions(testIssueID)
  28. for _, v := range possibleTransitions {
  29.   if v.Name == "In Progress" {
  30.    transitionID = v.ID
  31.    break
  32.   }
  33. }

  35. jiraClient.Issue.DoTransition(testIssueID, transitionID)
  36. issue, _, _ = jiraClient.Issue.Get(testIssueID, nil)
  37. fmt.Printf("Status after transition: %+v\n", issue.Fields.Status.Name)
  38. }
  39. ```

Get all the issues for JQL with Pagination


Jira API has limit on maxResults it can return. You may have a usecase where you need to get all issues for given JQL. This example shows reference implementation of GetAllIssues function which does pagination on Jira API to get all the issues for given JQL.

Please look at Pagination Example

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 Atlassians Jira instance`.

  1. ``` go
  2. package main

  4. import (
  5. "fmt"
  6. "github.com/andygrunwald/go-jira"
  7. )

  9. func main() {
  10. base := "https://my.jira.com"
  11. tp := jira.BasicAuthTransport{
  12.   Username: "username",
  13.   Password: "token",
  14. }

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

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

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

  29. // ...
  30. // BAM: Bamboo
  31. // BAMJ: Bamboo Jira Plugin
  32. // CLOV: Clover
  33. // CONF: Confluence
  34. // ...
  35. }
  36. ```

Implementations


andygrunwald/jitic - The Jira Ticket Checker

Development


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.

Unit testing


To run the local unit tests, execute

  1. ``` shell
  2. $ make test
  3. ```

To run the local unit tests and view the unit test code coverage in your local web browser, execute

  1. ``` shell
  2. $ make test-coverage-html
  3. ```

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.

Supported Go versions


We follow the Go Release Policy :

Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release. We fix critical problems, including critical security problems, in supported releases as needed by issuing minor revisions (for example, Go 1.6.1, Go 1.6.2, and so on).


Supported Jira versions


Jira Server (On-Premise solution)


We follow the Atlassian Support End of Life Policy :

Atlassian supports feature versions for two years after the first major iteration of that version was released (for example, we support Jira Core 7.2.x for 2 years after Jira 7.2.0 was released).


Jira Cloud


We support Jira Cloud API in version 3. Even if this API version is currentlyin beta (by Atlassian):

Version 2 and version 3 of the API offer the same collection of operations. However, version 3 provides support for the Atlassian Document Format (ADF) in a subset of the API.

Official Jira API documentation


Jira Server (On-Premise solution)
Jira Cloud API in version 2
Jira Cloud API in version 3

Sandbox environment for testing


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

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

Releasing


Install standard-version

  1. ``` shell
  2. npm i -g standard-version
  3. ```

  1. ``` shell
  2. standard-version
  3. git push --tags
  4. ```

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.