circleci

README

CircleCI Go Client

Go API Client for CircleCI. Currently implements the v1.1 API (https://circleci.com/docs/api).

Currently under active development

Usage:

Installation:

Change directory to you project dir and run:

go get mickey.dev/go/circleci-go@latest

Import the package:

package somePackage

import (
    "log"
    "context"

    "mickey.dev/go/circleci-go"
)

const (
    API_TOKEN = "YourCircleCIAPIToken"
    SERVER_URL = "https://circleci.com"
)

func main() {
    client, err := circleci.NewClient(API_TOKEN, SERVER_URL)
    if err != nil {
        log.Fatalf("Couldn't create new CircleCI API Client: %v", err)
    }

    // Example call - List all followed projects:
    projects, _ := client.Projects.List(context.Background())
}

Development

Currently this package is incomplete and under active development. PRs are welcome!

To configure your build environment:

1. Fork the repo.
2. Clone: git clone git@github.com/<YOUR_GITHUB_USERNAME>/circleci-go.git
3. cd circleci-go
4. go get
5. go test ./... - Confirm the tests pass!

Run Integration Tests

The integration tests will attempt to reach out to the live CircleCI API. As a result you'll need to retreive an API token from CircleCI and set the following environment variable:

export CIRCLECI_KEY=<YOUR_CIRCLECI_API_KEY>

You may wish to change the project the tests are run against, you can do this from within the integration_test.go file.

To run the tests use the following command:

go test -tags=integration

To Do

• Everything.
• /me endpoints.
• Jobs and Workflows.

Documentation

Index

• Constants
• func WithBaseHTTPClient(client *http.Client) func(*Client) error
• func WithBaseServerURL(u string) func(*Client) error
• func WithVCSType(vcs string) func(*Client) error
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(apiKey string, opts ...ClientOption) (*Client, error)
  • func (c *Client) GetHTTPClient() *http.Client
• type ClientOption
• type Project
• type ProjectService
  • func (p *ProjectService) Disable(ctx context.Context, project, username string) error
  • func (p *ProjectService) Enable(ctx context.Context, project string, username string) error
  • func (p *ProjectService) EnableAndFollow(ctx context.Context, project, username string) error
  • func (p *ProjectService) Follow(ctx context.Context, project string, username string) error
  • func (p *ProjectService) Get(ctx context.Context, proj string, username string) (*Project, error)
  • func (p *ProjectService) List(ctx context.Context) ([]*Project, error)
  • func (p *ProjectService) Unfollow(ctx context.Context, project string, username string) error

Examples

• WithBaseHTTPClient

Constants

const (
	VCSTypeGitHub    = "github"
	VCSTypeBitBucket = "bitbucket"
)

Functions

func WithBaseHTTPClient

func WithBaseHTTPClient(client *http.Client) func(*Client) error

WithBaseHTTPClient returns a function that accepts a *Client value, and modifies the underlying http.Client object. Pass this function into the NewClient() function as an optional variadic parameter.

Example

httpClient := &http.Client{}

_, err := circleci.NewClient("YourCircleCIAPIToken", circleci.WithBaseHTTPClient(httpClient))
if err != nil {
	log.Fatal(err)
}

func WithBaseServerURL

func WithBaseServerURL(u string) func(*Client) error

func WithVCSType

func WithVCSType(vcs string) func(*Client) error

Types

type APIError

type APIError struct {
	StatusCode int    `json:"statusCode,omitempty"`
	Message    string `json:"message"`
}

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {

	// APIKey stores the CircleCI API Token. Generate a CircleCI token by navigating
	// to https://circleci.com/account/api and generating a new token.
	//
	// The API token is required in order to communicate with the CircleCI API server.
	// The authenticated user should be "Following" the projects they want to make
	// changes to.
	//
	// New projects can also be followed by using the client.Projects.Follow() API.
	APIKey string

	// ServerURL should be the CircleCI server URL to make API calls against.
	//
	// For CircleCI SaaS use https://circleci.com/. For CircleCI Server (previously
	// Enterprise) use your internal CircleCI URL. If your CircleCI Server requires a
	// custom port that isn't 443, then include this in the URL.
	// E.g. https://circle.company.com:8080/
	BaseURL *url.URL

	// VCSType is the Version Control System that hosts the CircleCI projects you wish
	// manipulate via CircleCI API. This is also included in API path when calling the
	// CircleCI API. This will be either "github" or "bitbucket".
	//
	// The default VCSTypeis "github" and can be overridden by passing the WithVCSType
	// option function when calling NewClient().
	VCSType string

	// Projects represents the CircleCI project resources. This will be instantiated
	// by default with a *circleci.ProjectService object when circleci.NewClient() is
	// called.
	Projects *ProjectService
	// contains filtered or unexported fields
}

func NewClient

func NewClient(apiKey string, opts ...ClientOption) (*Client, error)

func (*Client) GetHTTPClient

func (c *Client) GetHTTPClient() *http.Client

type ClientOption

type ClientOption func(*Client) error

type Project

type Project struct {
	Name     string `json:"reponame"`
	Username string `json:"username"`
	Followed bool   `json:"followed"`
	URL      string `json:"vcs_url"`
}

Project type models the returned values from the /projects endpoint of the CircleCI API.

type ProjectService

type ProjectService struct {
	// contains filtered or unexported fields
}

ProjectService handles communication with the project related methods of the CircleCI API. https://circleci.com/docs/api/#projects

func (*ProjectService) Disable

func (p *ProjectService) Disable(ctx context.Context, project, username string) error

Disable will remove the CircleCI deploy key from the repo. The authenicated user must have "admin" permissions on the repo.

func (*ProjectService) Enable

func (p *ProjectService) Enable(ctx context.Context, project string, username string) error

Enable the project in CircleCI, this will generate and add an SSH to the repo for code checkout. The authenticated user must have "admin" permissions on the rpeo.

func (*ProjectService) EnableAndFollow

func (p *ProjectService) EnableAndFollow(ctx context.Context, project, username string) error

EnableAndFollow is a helper funtion that will enable the project, and then follow the enabled project.

func (*ProjectService) Follow

func (p *ProjectService) Follow(ctx context.Context, project string, username string) error

func (*ProjectService) Get

func (p *ProjectService) Get(ctx context.Context, proj string, username string) (*Project, error)

Get retreives a project based on the project name and owner (GitHub Username). The authenticated user must be "following" the project in order to retrieve it.

func (*ProjectService) List

func (p *ProjectService) List(ctx context.Context) ([]*Project, error)

List returns a slice containing all projects followed by the authenticated user.

func (*ProjectService) Unfollow

func (p *ProjectService) Unfollow(ctx context.Context, project string, username string) error