etsangsplk/codeship-go

Go library for accessing the Codeship API v2

Codeship API (v2) Client for Go

Codeship API v2 client for Go.

Documentation

https://godoc.org/github.com/codeship/codeship-go

Usage

go get -u github.com/codeship/codeship-go

Package codeship provides a client for using the Codeship API v2.

import codeship "github.com/codeship/codeship-go"

Create a new API Client:

auth := codeship.NewBasicAuth("username", "password")
client, err := codeship.New(auth)

You must then scope the client to a single Organization that you have access to:

org, err := client.Organization(ctx, "codeship")

You can then perform calls to the API on behalf of an Organization:

projects, err := org.ListProjects(ctx)

Authentication

Authentication is handled automatically via the API Client using the provided authentication mechanism.

If you would like to manually re-authenticate, you may do this by calling the Authenticate method on the client:

err := client.Authenticate(ctx)

Two-Factor Authentication

Codeship now supports Two-Factor Authentication (2FA).

However, it is currently not possible to use 2FA with the API. If you try to authenticate via this client with a user that has 2FA enabled you will get the following error:

authentication failed: your account has two-factor authentication enabled, which is not possible to support with the API. Disable two factor authentication or create a dedicated API user without it enabled.

You must disable 2FA for the user you wish to authenticate with using this client. We hope to support Personal Access Tokens in a future version of the API to mitigate this issue.

Response

All API methods also return a codeship.Response type that contains the actual *http.Response embedded as well as a Links type that contains information to be used for pagination.

Pagination

Pagination is provided for all requests that can return multiple results. The methods that are able to be paginated all take a variable argument of type PaginationOption such as: ListProjects(opts ...PaginationOption).

We have defined two helper functions, Page and PerPage, to make pagination easier.

Usage is as follows:

// defaults to first page with page_size of 30
projects, resp, err := org.ListProjects(ctx)

// paging forwards with 50 results per page
for {
    if resp.IsLastPage() || resp.Next == "" {
        break
    }

    next, _ := resp.NextPage()

    projects, resp, _ = org.ListProjects(ctx, codeship.Page(next), codeship.PerPage(50))
}

// paging backwards with 50 results per page
for {
    if current, _ := resp.CurrentPage(); current == 1 || resp.Previous == "" {
        break
    }

    prev, _ := resp.PreviousPage()

    projects, resp, _ = org.ListProjects(ctx, codeship.Page(prev), codeship.PerPage(50))
}

Logging

You can enable verbose logging of all HTTP requests/responses by configuring the client via the functional option Verbose(verbose bool) when instantiating the client:

auth := codeship.NewBasicAuth("username", "password")
client, err := codeship.New(auth, codeship.Verbose(true))

The default logger logs to STDOUT but can be replaced by any instance of *log.Logger:

var (
    buf    bytes.Buffer
    logger = log.New(&buf, "INFO: ", log.Lshortfile)
    auth   = codeship.NewBasicAuth("username", "password")
)

client, err := codeship.New(auth, codeship.Verbose(true), codeship.Logger(logger))

Contributing

This project follows Codeship's Go best practices. Please review them and make sure your PR follows the guidelines laid out before submitting.

Everyone interacting in the project and its sub-projects' codebases, issue trackers, chat rooms, and mailing lists is expected to follow the Code of Conduct.

Setup

This project uses dep for dependency management.

To install/update dep and all dependencies, run:

make setup
make dep

Testing

make test

We aim for > 80% test coverage. You can view the current coverage info by running:

make cover

Linting

make lint

Other

$ make help

setup                          Install all the build and lint dependencies
dep                            Run dep ensure and prune
test                           Run all the tests
cover                          Run all the tests and opens the coverage report
fmt                            goimports all go files
lint                           Run all the linters
ci                             Run all the tests and code checks
build                          Build a version
clean                          Remove temporary files