{"id":13367183,"url":"https://github.com/andygrunwald/Go-jira","last_synced_at":"2025-03-12T18:32:04.301Z","repository":{"id":1220067,"uuid":"41102121","full_name":"andygrunwald/go-jira","owner":"andygrunwald","description":"Go client library for Atlassian Jira","archived":false,"fork":false,"pushed_at":"2025-03-01T07:10:59.000Z","size":2020,"stargazers_count":1506,"open_issues_count":176,"forks_count":475,"subscribers_count":30,"default_branch":"main","last_synced_at":"2025-03-06T07:47:07.679Z","etag":null,"topics":["atlassian-jira","hacktoberfest","jira","jira-api","jira-client"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/andygrunwald/go-jira?tab=doc","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andygrunwald.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/supported-environments.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["andygrunwald","benjivesterby"],"custom":"https://paypal.me/andygrunwald"}},"created_at":"2015-08-20T15:02:46.000Z","updated_at":"2025-03-01T07:10:45.000Z","dependencies_parsed_at":"2024-06-01T10:28:15.777Z","dependency_job_id":"7e2ed2a9-f8b0-4735-a0dc-3f23e694b74e","html_url":"https://github.com/andygrunwald/go-jira","commit_stats":{"total_commits":635,"total_committers":140,"mean_commits":4.535714285714286,"dds":0.6220472440944882,"last_synced_commit":"48c5a07771b63cda984b1c0845a8199b7ad61d61"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygrunwald%2Fgo-jira","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygrunwald%2Fgo-jira/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygrunwald%2Fgo-jira/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygrunwald%2Fgo-jira/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andygrunwald","download_url":"https://codeload.github.com/andygrunwald/go-jira/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243271491,"owners_count":20264464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atlassian-jira","hacktoberfest","jira","jira-api","jira-client"],"created_at":"2024-07-30T00:01:40.813Z","updated_at":"2025-03-12T18:32:03.873Z","avatar_url":"https://github.com/andygrunwald.png","language":"Go","funding_links":["https://github.com/sponsors/andygrunwald","https://github.com/sponsors/benjivesterby","https://paypal.me/andygrunwald"],"categories":["第三方 APIs"],"sub_categories":["高级控制台界面","高級控制台界面"],"readme":"# go-jira\n\n[![GoDoc](https://pkg.go.dev/badge/github.com/andygrunwald/go-jira?utm_source=godoc)](https://pkg.go.dev/github.com/andygrunwald/go-jira)\n[![Build Status](https://github.com/andygrunwald/go-jira/actions/workflows/testing.yml/badge.svg)](https://github.com/andygrunwald/go-jira/actions/workflows/testing.yml)\n[![Go Report Card](https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat)](https://goreportcard.com/report/github.com/andygrunwald/go-jira)\n\n[Go](https://go.dev/) client library for [Atlassian Jira](https://www.atlassian.com/software/jira).\n\n![Go client library for Atlassian Jira](./img/logo_small.png \"Go client library for Atlassian Jira.\")\n\n## :warning: State of this library :warning:\n\n**v2 of this library is in development.**\n**v2 will contain breaking changes :warning:**\n**The current main branch contains the development version of v2.**\n\nThe goals of v2 are:\n\n* idiomatic go usage\n* proper documentation\n* being compliant with different kinds of Atlassian Jira products (on-premise vs. cloud)\n* remove flaws introduced during the early times of this library\n\nSee our milestone [Road to v2](https://github.com/andygrunwald/go-jira/milestone/1) and provide feedback in [Development is kicking: Road to v2 🚀 #489](https://github.com/andygrunwald/go-jira/issues/489).\nAttention: The current `main` branch represents the v2 development version - we treat this version as unstable and breaking changes are expected.\n\n**If you want to stay more stable, please use v1.\\*** - See our [releases](https://github.com/andygrunwald/go-jira/releases).\nLatest stable release: [v1.16.0](https://github.com/andygrunwald/go-jira/releases/tag/v1.16.0)\n\n## Features\n\n* Authentication (HTTP Basic, OAuth, Session Cookie, Bearer (for PATs))\n* Create and retrieve issues\n* Create and retrieve issue transitions (status updates)\n* Call every API endpoint of the Jira, even if it is not directly implemented in this library\n\nThis 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 Jira have a look at [latest Jira REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/).\n\n## Requirements\n\n* Go \u003e= 1.14\n* Jira v6.3.4 \u0026 v7.1.2.\n\nNote that we also run our tests against 1.13, though only the last two versions\nof Go are officially supported.\n\n## Installation\n\nIt is go gettable\n\n```sh\ngo get github.com/andygrunwald/go-jira\n```\n\n## API\n\nPlease have a look at the [GoDoc documentation](https://pkg.go.dev/github.com/andygrunwald/go-jira) for a detailed API description.\n\nThe [latest Jira REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) was the base document for this package.\n\n## Examples\n\nFurther a few examples how the API can be used.\nA few more examples are available in the [GoDoc examples section](https://pkg.go.dev/github.com/andygrunwald/go-jira#section-directories).\n\n### Get a single issue\n\nLets retrieve [MESOS-3325](https://issues.apache.org/jira/browse/MESOS-3325) from the [Apache Mesos](http://mesos.apache.org/) project.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\tjira \"github.com/andygrunwald/go-jira\"\n)\n\nfunc main() {\n\tjiraClient, _ := jira.NewClient(nil, \"https://issues.apache.org/jira/\")\n\tissue, _, _ := jiraClient.Issue.Get(\"MESOS-3325\", nil)\n\n\tfmt.Printf(\"%s: %+v\\n\", issue.Key, issue.Fields.Summary)\n\tfmt.Printf(\"Type: %s\\n\", issue.Fields.Type.Name)\n\tfmt.Printf(\"Priority: %s\\n\", issue.Fields.Priority.Name)\n\n\t// MESOS-3325: Running mesos-slave@0.23 in a container causes slave to be lost after a restart\n\t// Type: Bug\n\t// Priority: Critical\n}\n```\n\n### Authentication\n\nThe `go-jira` library does not handle most authentication directly.  Instead, authentication should be handled within\nan `http.Client`. That client can then be passed into the `NewClient` function when creating a jira client.\n\nFor convenience, capability for basic and cookie-based authentication is included in the main library.\n\n#### Token (Jira on Atlassian Cloud)\n\nToken-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](https://id.atlassian.com/manage-profile/security/api-tokens). Additional information about Atlassian Cloud API tokens can be found [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).\n\nA more thorough, [runnable example](cloud/examples/basic_auth/main.go) is provided in the examples directory.\n\n```go\nfunc main() {\n\ttp := jira.BasicAuthTransport{\n\t\tUsername: \"\u003cusername\u003e\",\n\t\tAPIToken: \"\u003capi-token\u003e\",\n\t}\n\n\tclient, err := jira.NewClient(tp.Client(), \"https://my.jira.com\")\n\n\tu, _, err = client.User.GetCurrentUser(context.Background())\n\n\tfmt.Printf(\"Email: %v\\n\", u.EmailAddress)\n\tfmt.Println(\"Success!\")\n}\n```\n\n#### Bearer - Personal Access Tokens (self-hosted Jira)\n\nFor **self-hosted Jira** (v8.14 and later), Personal Access Tokens (PATs) were introduced.\nSimilar to the API tokens, PATs are a safe alternative to using username and password for authentication with scripts and integrations.\nPATs use the Bearer authentication scheme.\nRead more about Jira PATs [here](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).\n\nSee [examples/bearerauth](onpremise/examples/bearerauth/main.go) for how to use the Bearer authentication scheme with Jira in Go.\n\n#### Basic (self-hosted Jira)\n\nPassword-based API authentication works for self-hosted Jira **only**, and has been [deprecated for users of Atlassian Cloud](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-basic-auth-and-cookie-based-auth/).\n\nDepending on your version of Jira, either of the above token authentication examples may be used, substituting a user's password for a generated token.\n\n#### Authenticate with OAuth\n\nIf you want to connect via OAuth to your Jira Cloud instance checkout the [example of using OAuth authentication with Jira in Go](https://gist.github.com/Lupus/edafe9a7c5c6b13407293d795442fe67) by [@Lupus](https://github.com/Lupus).\n\nFor more details have a look at the [issue #56](https://github.com/andygrunwald/go-jira/issues/56).\n\n### Create an issue\n\nExample how to create an issue.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/andygrunwald/go-jira\"\n)\n\nfunc main() {\n\tbase := \"https://my.jira.com\"\n\ttp := jira.BasicAuthTransport{\n\t\tUsername: \"username\",\n\t\tPassword: \"token\",\n\t}\n\n\tjiraClient, err := jira.NewClient(tp.Client(), base)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\ti := jira.Issue{\n\t\tFields: \u0026jira.IssueFields{\n\t\t\tAssignee: \u0026jira.User{\n\t\t\t\tName: \"myuser\",\n\t\t\t},\n\t\t\tReporter: \u0026jira.User{\n\t\t\t\tName: \"youruser\",\n\t\t\t},\n\t\t\tDescription: \"Test Issue\",\n\t\t\tType: jira.IssueType{\n\t\t\t\tName: \"Bug\",\n\t\t\t},\n\t\t\tProject: jira.Project{\n\t\t\t\tKey: \"PROJ1\",\n\t\t\t},\n\t\t\tSummary: \"Just a demo issue\",\n\t\t},\n\t}\n\tissue, _, err := jiraClient.Issue.Create(\u0026i)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Printf(\"%s: %+v\\n\", issue.Key, issue.Fields.Summary)\n}\n```\n\n### Change an issue status\n\nThis is how one can change an issue status. In this example, we change the issue from \"To Do\" to \"In Progress.\"\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/andygrunwald/go-jira\"\n)\n\nfunc main() {\n        testIssueID := \"FART-1\"\n\tbase := \"https://my.jira.com\"\n\ttp := jira.BasicAuthTransport{\n\t\tUsername: \"username\",\n\t\tPassword: \"token\",\n\t}\n\n\tjiraClient, err := jira.NewClient(tp.Client(), base)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tissue, _, _ := jiraClient.Issue.Get(testIssueID, nil)\n\tcurrentStatus := issue.Fields.Status.Name\n\tfmt.Printf(\"Current status: %s\\n\", currentStatus)\n\n\tvar transitionID string\n\tpossibleTransitions, _, _ := jiraClient.Issue.GetTransitions(testIssueID)\n\tfor _, v := range possibleTransitions {\n\t\tif v.Name == \"In Progress\" {\n\t\t\ttransitionID = v.ID\n\t\t\tbreak\n\t\t}\n\t}\n\n\tjiraClient.Issue.DoTransition(testIssueID, transitionID)\n\tissue, _, _ = jiraClient.Issue.Get(testIssueID, nil)\n\tfmt.Printf(\"Status after transition: %+v\\n\", issue.Fields.Status.Name)\n}\n```\n\n### Get all the issues for JQL with Pagination\n\nJira API has limit on maxResults it can return. You may have a usecase where you need to get all issues for given JQL.\nThis example shows reference implementation of GetAllIssues function which does pagination on Jira API to get all the issues for given JQL.\n\nPlease look at [Pagination Example](https://github.com/andygrunwald/go-jira/blob/main/cloud/examples/pagination/main.go)\n\n### Call a not implemented API endpoint\n\nNot all API endpoints of the Jira API are implemented into *go-jira*.\nBut you can call them anyway:\nLets get all public projects of [Atlassian`s Jira instance](https://jira.atlassian.com/).\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/andygrunwald/go-jira\"\n)\n\nfunc main() {\n\tbase := \"https://my.jira.com\"\n\ttp := jira.BasicAuthTransport{\n\t\tUsername: \"username\",\n\t\tPassword: \"token\",\n\t}\n\n\tjiraClient, err := jira.NewClient(tp.Client(), base)\n\treq, _ := jiraClient.NewRequest(\"GET\", \"rest/api/2/project\", nil)\n\n\tprojects := new([]jira.Project)\n\t_, err = jiraClient.Do(req, projects)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfor _, project := range *projects {\n\t\tfmt.Printf(\"%s: %s\\n\", project.Key, project.Name)\n\t}\n\n\t// ...\n\t// BAM: Bamboo\n\t// BAMJ: Bamboo Jira Plugin\n\t// CLOV: Clover\n\t// CONF: Confluence\n\t// ...\n}\n```\n\n## Implementations\n\n* [andygrunwald/jitic](https://github.com/andygrunwald/jitic) - The Jira Ticket Checker\n\n## Development\n\n### Code structure\n\nThe code structure of this package was inspired by [google/go-github](https://github.com/google/go-github).\n\nThere is one main part (the client).\nBased on this main client the other endpoints, like Issues or Authentication are extracted in services. E.g. `IssueService` or `AuthenticationService`.\nThese services own a responsibility of the single endpoints / usecases of Jira.\n\n### Unit testing\n\nTo run the local unit tests, execute\n\n```sh\n$ make test\n```\n\nTo run the local unit tests and view the unit test code coverage in your local web browser, execute\n\n```sh\n$ make test-coverage-html\n```\n\n## Contribution\n\nWe ❤️ PR's\n\nContribution, in any kind of way, is highly welcome!\nIt doesn't matter if you are not able to write code.\nCreating issues or holding talks and help other people to use [go-jira](https://github.com/andygrunwald/go-jira) is contribution, too!\nA few examples:\n\n* Correct typos in the README / documentation\n* Reporting bugs\n* Implement a new feature or endpoint\n* Sharing the love of [go-jira](https://github.com/andygrunwald/go-jira) and help people to get use to it\n\nIf you are new to pull requests, checkout [Collaborating on projects using issues and pull requests / Creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).\n\n### Supported Go versions\n\nWe follow the [Go Release Policy](https://go.dev/doc/devel/release#policy):\n\n\u003e 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](https://go.dev/security/), in supported releases as needed by issuing minor revisions (for example, Go 1.6.1, Go 1.6.2, and so on).\n\n### Supported Jira versions\n\n#### Jira Server (On-Premise solution)\n\nWe follow the [Atlassian Support End of Life Policy](https://confluence.atlassian.com/support/atlassian-support-end-of-life-policy-201851003.html):\n\n\u003e 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).\n\n#### Jira Cloud\n\nWe support Jira Cloud API in [version 3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/).\nEven if this API version is _currently_ in beta (by Atlassian):\n\n[Version 2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and version 3 of the API offer the same collection of operations.\nHowever, version 3 provides support for the [Atlassian Document Format (ADF)](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) in a subset of the API.\n\n### Official Jira API documentation\n\n* [Jira Server (On-Premise solution)](https://developer.atlassian.com/server/jira/platform/rest-apis/)\n* Jira Cloud API in [version 2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/)\n* Jira Cloud API in [version 3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)\n\n### Sandbox environment for testing\n\nJira offers sandbox test environments at http://go.atlassian.com/cloud-dev.\n\nYou can read more about them at https://blog.developer.atlassian.com/cloud-ecosystem-dev-env/.\n\n## Releasing\n\nInstall [standard-version](https://github.com/conventional-changelog/standard-version)\n\n```bash\nnpm i -g standard-version\n```\n\n```bash\nstandard-version\ngit push --tags\n```\n\nManually copy/paste text from changelog (for this new version) into the release on Github.com. E.g.\n\n[https://github.com/andygrunwald/go-jira/releases/edit/v1.11.0](https://github.com/andygrunwald/go-jira/releases/edit/v1.11.0)\n\n## License\n\nThis project is released under the terms of the [MIT license](http://en.wikipedia.org/wiki/MIT_License).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandygrunwald%2FGo-jira","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandygrunwald%2FGo-jira","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandygrunwald%2FGo-jira/lists"}