go-jira

The go-jira library does not handle authentication directly. Instead, authentication is managed within an http.Client. You create an http.Client (or an http.RoundTripper like jira.BasicAuthTransport) and pass it to jira.NewClient.

Supported schemes include:

• Basic Auth / API Tokens: Used for Jira Cloud (using an API token instead of a password) or self-hosted Jira.
• Bearer (PATs): Used for self-hosted Jira (v8.14+) via Personal Access Tokens.
• Session Cookie: For cookie-based authentication.
• OAuth: For connecting via OAuth.

In v2.0.0, you must select the package that matches your Jira deployment type. They are no longer unified.

• Jira Cloud: Use if your Jira URL ends with .atlassian.net. Import github.com/andygrunwald/go-jira/v2/cloud.
• Jira On-Premise: Use if your Jira is hosted on your own domain or servers. Import github.com/andygrunwald/go-jira/v2/onpremise.

Note: The APIs and authentication fields (like APIToken vs Password) differ between these packages.

v2.0.0 splits the library into two distinct packages because Jira Cloud and On-Premise (Server/Data Center) APIs have diverged. You must import the package that matches your deployment type:

You can install the go-jira v2 library using go get. Ensure your environment meets the requirements specified in the supported environments documentation before proceeding.

go get github.com/andygrunwald/go-jira/v2

Install the go-jira library using go get. This library is a Go client for Atlassian Jira.

Requirements:

• Go >= 1.14
• Jira v6.3.4 or v7.1.2 (or later versions compatible with the API)

go get github.com/andygrunwald/go-jira

Jira Cloud authentication is streamlined and requires using an API token via BasicAuthTransport.

Key Changes:

• Use github.com/andygrunwald/go-jira/v2/cloud.
• BasicAuthTransport.Password has been renamed to BasicAuthTransport.APIToken.
• BearerAuthTransport, PATAuthTransport, and CookieAuthTransport are no longer supported for Cloud.

import jira "github.com/andygrunwald/go-jira/v2/cloud"

tp := jira.BasicAuthTransport{
    Username: "user@example.com",
    APIToken: "your-api-token",  // Note: Field renamed from Password to APIToken
}
client, err := jira.NewClient("https://example.atlassian.net/", tp.Client())

Migrating to v2.0.0 involves significant breaking changes due to the split between Jira Cloud and On-Premise APIs.

Quick Checklist

• Update go.mod to use github.com/andygrunwald/go-jira/v2.
• Change imports to use either the /v2/cloud or /v2/onpremise subpackages.
• Swap NewClient arguments: use NewClient(baseURL, httpClient) (previously NewClient(httpClient, baseURL)).
• Add context.Context as the first argument to all service method calls.
• Remove WithContext suffix from method names (e.g., GetWithContext becomes Get).
• Update authentication transport field names (Cloud: Password -> APIToken).

Prerequisites

• Go Version: Requires Go 1.21 or later.

In v2.0.0, all API methods (both Request methods and Service methods) require a context.Context as their first argument. The previous *WithContext suffix methods have been removed.

Migration Patterns:

• For a quick migration, use context.Background() or context.TODO().
• For production code, use a context with a timeout (e.g., context.WithTimeout).

// Quick migration
issue, resp, err := client.Issue.Get(context.Background(), "KEY-123", nil)

// Better: use a proper context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
issue, resp, err := client.Issue.Get(ctx, "KEY-123", nil)