go-atlassian is a Go library that provides a simple and convenient way to interact with various Atlassian products' REST APIs. Atlassian is a leading provider of software and tools for software development, project management, and collaboration. Some of the products that go-atlassian supports include Jira, Confluence, Jira Service Management, and more.
The go-atlassian library is designed to simplify the process of building Go applications that interact with Atlassian products. It provides a set of functions and data structures that can be used to easily send HTTP requests to the Atlassian APIs, parse the responses, and work with the data returned.
- Easy-to-use functions and data structures that abstract away much of the complexity of working with the APIs.
- Comprehensive support for various Atlassian products' APIs.
- Support for common operations like creating, updating, and deleting entities in Atlassian products.
- Active development and maintenance by the community, with regular updates and bug fixes.
- Comprehensive documentation and examples to help developers get started with using the library.
If you do not have Go installed yet, you can find installation instructions here. Please note that the package requires Go version 1.20 or later for module support.
To pull the most recent version of go-atlassian, use go get.
go get github.com/ctreminiom/go-atlassian/v2
Then import the package into your project as you normally would. You can import the following packages:
| Module | Path | URL's |
|---|---|---|
| Jira v2 | github.com/ctreminiom/go-atlassian/v2/jira/v2 |
Getting Started |
| Jira v3 | github.com/ctreminiom/go-atlassian/v2/jira/v3 |
Getting Started |
| Jira Software Agile | github.com/ctreminiom/go-atlassian/v2/jira/agile |
Getting Started |
| Jira Service Management | github.com/ctreminiom/go-atlassian/v2/jira/sm |
Getting Started |
| Jira Assets | github.com/ctreminiom/go-atlassian/v2/assets |
Getting Started |
| Confluence | github.com/ctreminiom/go-atlassian/v2/confluence |
Getting Started |
| Confluence v2 | github.com/ctreminiom/go-atlassian/v2/confluence/v2 |
Getting Started |
| Admin Cloud | github.com/ctreminiom/go-atlassian/v2/admin |
Getting Started |
| Bitbucket Cloud (In Progress) | github.com/ctreminiom/go-atlassian/v2/bitbucket |
Getting Started |
Before using the go-atlassian package, you need to have an Atlassian API key. If you do not have a key yet, you can sign up here.
Create a client with your instance host and access token to start communicating with the Atlassian API's. In this example, we're going to instance a new Confluence Cloud client.
instance, err := confluence.New(nil, "INSTANCE_HOST")
if err != nil {
log.Fatal(err)
}
instance.Auth.SetBasicAuth("YOUR_CLIENT_MAIL", "YOUR_APP_ACCESS_TOKEN")If you need to use a preconfigured HTTP client, simply pass its address to the New function.
transport := http.Transport{
Proxy: http.ProxyFromEnvironment,
Dial: (&net.Dialer{
// Modify the time to wait for a connection to establish
Timeout: 1 * time.Second,
KeepAlive: 30 * time.Second,
}).Dial,
TLSHandshakeTimeout: 10 * time.Second,
}
client := http.Client{
Transport: &transport,
Timeout: 4 * time.Second,
}
instance, err := confluence.New(&client, "INSTANCE_HOST")
if err != nil {
log.Fatal(err)
}
instance.Auth.SetBasicAuth("YOUR_CLIENT_MAIL", "YOUR_APP_ACCESS_TOKEN")go-atlassian now supports OAuth 2.0 (3-legged OAuth) authentication across all API clients for building apps that authenticate on behalf of users. This allows your app to access Atlassian APIs using the permissions granted by users.
Supported clients: Jira v2, Jira v3, Jira Agile, Jira Service Management, Confluence v1, Confluence v2, Admin, Assets, and Bitbucket.
First, create an OAuth 2.0 app in the Atlassian Developer Console to get your client ID and client secret.
// Configure OAuth
oauthConfig := &common.OAuth2Config{
ClientID: "YOUR_CLIENT_ID",
ClientSecret: "YOUR_CLIENT_SECRET",
RedirectURI: "https://your-app.com/callback",
}
// Create client with OAuth support for the authorization flow
client, err := jira.New(
http.DefaultClient,
"https://api.atlassian.com", // Temporary URL for OAuth flow
jira.WithOAuth(oauthConfig),
)
if err != nil {
log.Fatal(err)
}
// Generate authorization URL
scopes := []string{"read:jira-work", "write:jira-work"}
authURL, err := client.OAuth.GetAuthorizationURL(scopes, "state")
if err != nil {
log.Fatal(err)
}
// Direct user to authURL to authorize your app
fmt.Printf("Visit this URL to authorize: %s\n", authURL.String())
// After authorization, exchange code for tokens
ctx := context.Background()
token, err := client.OAuth.ExchangeAuthorizationCode(ctx, "AUTH_CODE")
if err != nil {
log.Fatal(err)
}
// Option 1: Manual token management
client.Auth.SetBearerToken(token.AccessToken)
// Option 2: Create new client with auto-renewal (recommended)
client, err = jira.New(
http.DefaultClient,
"https://your-domain.atlassian.net",
jira.WithOAuth(oauthConfig), // OAuth service
jira.WithAutoRenewalToken(token), // Auto-renewal
)
if err != nil {
log.Fatal(err)
}
// Make API calls
myself, _, err := client.MySelf.Details(ctx, nil)
if err != nil {
log.Fatal(err)
}OAuth 2.0 works consistently across all supported clients. Here are examples for different Atlassian services:
// Confluence v2
confluenceClient, err := confluencev2.New(
http.DefaultClient,
"https://your-domain.atlassian.net",
confluencev2.WithOAuth(oauthConfig),
confluencev2.WithAutoRenewalToken(token),
)
// Admin
adminClient, err := admin.New(
http.DefaultClient,
admin.WithOAuth(oauthConfig),
admin.WithAutoRenewalToken(token),
)
// Jira Service Management
smClient, err := sm.New(
http.DefaultClient,
"https://your-domain.atlassian.net",
sm.WithOAuth(oauthConfig),
sm.WithAutoRenewalToken(token),
)
// Assets
assetsClient, err := assets.New(
http.DefaultClient,
"https://api.atlassian.com",
assets.WithOAuth(oauthConfig),
assets.WithAutoRenewalToken(token),
)OAuth 2.0 tokens can provide access to multiple Atlassian sites. Use the
GetAccessibleResources method to discover available sites:
resources, err := client.OAuth.GetAccessibleResources(ctx, token.AccessToken)
if err != nil {
log.Fatal(err)
}
for _, resource := range resources {
fmt.Printf("Site: %s (%s)\n", resource.Name, resource.URL)
// Create a client for this specific site
siteClient, err := jira.New(
http.DefaultClient,
resource.URL,
jira.WithOAuth(oauthConfig),
)
if err != nil {
continue
}
siteClient.Auth.SetBearerToken(token.AccessToken)
// Use siteClient for API calls to this site
}OAuth 2.0 access tokens expire. You have two options for handling token refresh:
newToken, err := client.OAuth.RefreshAccessToken(ctx, token.RefreshToken)
if err != nil {
log.Fatal(err)
}
// Update the access token
client.Auth.SetBearerToken(newToken.AccessToken)For long-running applications, you can enable automatic token renewal:
// Create client with automatic token renewal
client, err := jira.New(
http.DefaultClient,
"https://your-domain.atlassian.net",
jira.WithOAuth(oauthConfig), // OAuth service configuration
jira.WithAutoRenewalToken(token), // Enable auto-renewal with token
)
if err != nil {
log.Fatal(err)
}
// Alternative: Use the convenience method
client, err := jira.New(
http.DefaultClient,
"https://your-domain.atlassian.net",
jira.WithOAuthWithAutoRenewal(oauthConfig, token),
)
// Use the client normally - tokens will be automatically refreshed
// when they're about to expire (with a 5-minute buffer)
issues, _, err := client.Issue.Search(ctx, jql, options)The auto-renewal feature:
- Automatically refreshes tokens before they expire
- Reuses valid tokens to minimize API calls
- Updates refresh tokens when new ones are provided
- Thread-safe for concurrent use
For complete examples, see:
- examples/jira_oauth2_example.go - Basic OAuth flow
- examples/jira_oauth2_http_server_example.go - Full-featured HTTP server with OAuth flow
- examples/multi_service_oauth2_example.go - Using OAuth across multiple Atlassian services
For detailed examples and usage of the go-atlassian library, please refer to our Cookbook. This section provides step-by-step guides and code samples for common tasks and scenarios.
The library uses the services interfaces to provide a modular and flexible way to interact with Atlassian products' REST APIs. It defines a set of services interfaces that define the functionality of each API, and then provides implementations of those interfaces that can be used to interact with the APIs.
// BoardConnector represents the Jira boards.
// Use it to search, get, create, delete, and change boards.
type BoardConnector interface {
Get(ctx context.Context, boardID int) (*model.BoardScheme, *model.ResponseScheme, error)
Create(ctx context.Context, payload *model.BoardPayloadScheme) (*model.BoardScheme, *model.ResponseScheme, error)
Filter(ctx context.Context, filterID, startAt, maxResults int) (*model.BoardPageScheme, *model.ResponseScheme, error)
Backlog(ctx context.Context, boardID int, opts *model.IssueOptionScheme, startAt, maxResults int) (*model.BoardIssuePageScheme, *model.ResponseScheme, error)
Configuration(ctx context.Context, boardID int) (*model.BoardConfigurationScheme, *model.ResponseScheme, error)
Epics(ctx context.Context, boardID, startAt, maxResults int, done bool) (*model.BoardEpicPageScheme, *model.ResponseScheme, error)
IssuesWithoutEpic(ctx context.Context, boardID int, opts *model.IssueOptionScheme, startAt, maxResults int) (
*model.BoardIssuePageScheme, *model.ResponseScheme, error)
IssuesByEpic(ctx context.Context, boardID, epicID int, opts *model.IssueOptionScheme, startAt, maxResults int) (
*model.BoardIssuePageScheme, *model.ResponseScheme, error)
Issues(ctx context.Context, boardID int, opts *model.IssueOptionScheme, startAt, maxResults int) (*model.BoardIssuePageScheme,
*model.ResponseScheme, error)
Move(ctx context.Context, boardID int, payload *model.BoardMovementPayloadScheme) (*model.ResponseScheme, error)
Projects(ctx context.Context, boardID, startAt, maxResults int) (*model.BoardProjectPageScheme, *model.ResponseScheme, error)
Sprints(ctx context.Context, boardID, startAt, maxResults int, states []string) (*model.BoardSprintPageScheme,
*model.ResponseScheme, error)
IssuesBySprint(ctx context.Context, boardID, sprintID int, opts *model.IssueOptionScheme, startAt, maxResults int) (
*model.BoardIssuePageScheme, *model.ResponseScheme, error)
Versions(ctx context.Context, boardID, startAt, maxResults int, released bool) (*model.BoardVersionPageScheme,
*model.ResponseScheme, error)
Delete(ctx context.Context, boardID int) (*model.ResponseScheme, error)
Gets(ctx context.Context, opts *model.GetBoardsOptions, startAt, maxResults int) (*model.BoardPageScheme,
*model.ResponseScheme, error)
}Each service interface includes a set of methods that correspond to the available endpoints in the corresponding API. For example, the IssueService interface includes methods like Create, Update, and Get that correspond to the POST, PUT, and GET endpoints in the Jira Issues API.
Behind the scenes, the Create method on the IssueService interface is implemented by the issueService.Create function in the go-atlassian library. This function sends an HTTP request to the relevant endpoint in the Jira Issues API, using the credentials and configuration provided by the client, and then parses the response into a usable format.
Here's a little example about how to get the issue transitions using the Issue service.
ctx := context.Background()
issueKey := "KP-2"
expand := []string{"transitions"}
issue, response, err := atlassian.Issue.Get(ctx,issueKey, nil, expand)
if err != nil {
log.Fatal(err)
}
log.Println(issue.Key)
for _, transition := range issue.Transitions {
log.Println(transition.Name, transition.ID, transition.To.ID, transition.HasScreen)
}The rest of the service functions work much the same way; they are concise and behave as you would expect. The documentation contains several examples on how to use each service function.
If you need to interact with an Atlassian API endpoint that hasn't been implemented in the go-atlassian library yet, you can make a custom API request using the built-in Client.Call method to execute raw HTTP requests.
Please raise an issue in order to implement the endpoint
package main
import (
"context"
"fmt"
"github.com/ctreminiom/go-atlassian/v2/jira/v3"
"log"
"net/http"
"os"
)
type IssueTypeMetadata struct {
IssueTypes []struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
} `json:"issueTypes"`
}
func main() {
var (
host = os.Getenv("SITE")
mail = os.Getenv("MAIL")
token = os.Getenv("TOKEN")
)
atlassian, err := v3.New(nil, host)
if err != nil {
log.Fatal(err)
}
atlassian.Auth.SetBasicAuth(mail, token)
// Define the RAW endpoint
apiEndpoint := "rest/api/3/issue/createmeta/KP/issuetypes"
request, err := atlassian.NewRequest(context.Background(), http.MethodGet, apiEndpoint, "", nil)
if err != nil {
log.Fatal(err)
}
customResponseStruct := new(IssueTypeMetadata)
response, err := atlassian.Call(request, &customResponseStruct)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Status)
}If you would like to contribute to this project, please adhere to the following guidelines.
- Submit an issue describing the problem.
- Fork the repo and add your contribution.
- Follow the basic Go conventions found here.
- Create a pull request with a description of your changes.
Again, contributions are greatly appreciated!
The project was created with the purpose to provide a unique point to provide an interface for interacting with Atlassian products.
This module is highly inspired by the Go library https://github.com/andygrunwald/go-jira but focused on Cloud solutions.
The library shares many similarities with go-jira, including its use of service interfaces to define the functionality of each API, its modular and flexible approach to working with Atlassian products' API's. However, go-atlassian also adds several new features and improvements that are not present in go-jira.
Despite these differences, go-atlassian remains heavily inspired by go-jira, and many of the core design principles and patterns used in go-jira can be found in go-atlassian as well.
Copyright © 2023 Carlos Treminio. This project is MIT licensed.
We would like to extend our sincere thanks to the following sponsors for their generous support:
- Atlassian for providing us Atlassian Admin/Jira/Confluence Standard licenses.
- JetBrains for providing us with free licenses of GoLand
- GitBook for providing us non-profit / open-source plan so hence I would like to express my thanks here.