circleciclient

package
v8.81.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 21, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package circleciclient is devctl's client for the CircleCI API: the calls the repository set-up engine makes for a project — follow and unfollow and stop building (v1.1), the token's user, the project, its settings and checkout keys, its pipelines (paged) and their workflows and jobs (v2) — and nothing else. The token is a personal API token (architectbot's `CIRCLECI_API_TOKEN` for the reconciler, the person's for `devctl repo reconcile`); the org and repository name a project by their GitHub slug.

Index

Constants

View Source
const APIv2Suffix = "/api/v2"

APIv2Suffix is the path circleci.com serves the API v2 under. The agent-facing commands are configured with the API URL including it (https://circleci.com/api/v2); BaseURLFromAPIURL turns that into the host this client prefixes its paths to.

View Source
const DefaultBaseURL = "https://circleci.com"

DefaultBaseURL is CircleCI's public API host.

View Source
const KeyTypeDeployKey = "deploy-key"

KeyTypeDeployKey is the checkout key type CircleCI creates as a deploy key on the GitHub repository; a project without one cannot check out.

Variables

This section is empty.

Functions

func BaseURLFromAPIURL added in v8.81.0

func BaseURLFromAPIURL(apiURL string) string

BaseURLFromAPIURL returns the Config.BaseURL for an API v2 URL: the URL without its /api/v2 suffix.

func IsAPI

func IsAPI(err error) bool

IsAPI asserts apiError: CircleCI answered with an error status.

func IsInvalidConfig

func IsInvalidConfig(err error) bool

IsInvalidConfig asserts invalidConfigError.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound asserts notFoundError: CircleCI answered 404 — for a project, the repository is not followed.

func PipelineURL added in v8.81.0

func PipelineURL(org, repo string, number int64) string

PipelineURL is the pipeline's page in the CircleCI UI.

func WorkflowFailed

func WorkflowFailed(status string) bool

WorkflowFailed says whether a workflow status is a terminal failure: the tag it built is dead and the fix lands as the next tag.

func WorkflowRunning added in v8.81.0

func WorkflowRunning(status string) bool

WorkflowRunning says whether a workflow status is still moving.

func WorkflowSucceeded

func WorkflowSucceeded(status string) bool

WorkflowSucceeded says whether a workflow status is a finished success.

Types

type AdvancedSettings

type AdvancedSettings struct {
	// SetupWorkflows enables dynamic configuration: the setup workflow the
	// generated pipeline needs (`Use of setup workflows must be enabled in
	// project settings` otherwise).
	SetupWorkflows *bool `json:"setup_workflows,omitempty"`
}

AdvancedSettings are the settings under "advanced".

type CheckoutKey

type CheckoutKey struct {
	Type        string    `json:"type"`
	Preferred   bool      `json:"preferred"`
	Fingerprint string    `json:"fingerprint"`
	PublicKey   string    `json:"public_key"`
	CreatedAt   time.Time `json:"created_at"`
}

CheckoutKey is a key CircleCI checks the repository out with.

type Client

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

Client calls the CircleCI API.

func New

func New(config Config) (*Client, error)

New returns a Client for config.

func (*Client) CreateCheckoutKey

func (c *Client) CreateCheckoutKey(ctx context.Context, org, repo, keyType string) (*CheckoutKey, error)

CreateCheckoutKey creates a checkout key of keyType (KeyTypeDeployKey or user-key); CircleCI installs a deploy key on the GitHub repository.

func (*Client) FindPipelineByTag added in v8.81.0

func (c *Client) FindPipelineByTag(ctx context.Context, org, repo, tag string) (*Pipeline, error)

FindPipelineByTag returns the newest pipeline of org/repo that built tag, or nil when the newest pipelines do not include one: the tag's webhook has not reached CircleCI yet, or never will.

func (*Client) Follow

func (c *Client) Follow(ctx context.Context, org, repo string) error

Follow follows the GitHub repository org/repo (v1.1). CircleCI builds the default branch at once with whatever .circleci/config.yml it carries and refuses an empty repository, so the scaffold is pushed first.

func (*Client) Following added in v8.64.8

func (c *Client) Following(ctx context.Context, org, repo string) (bool, error)

Following says whether the token's user follows org/repo (v1.1 project settings): the state Follow and Unfollow change. IsNotFound when CircleCI does not know the project.

func (*Client) GetProject

func (c *Client) GetProject(ctx context.Context, org, repo string) (*Project, error)

GetProject returns the project of org/repo; IsNotFound when CircleCI does not know it, which for a repository on GitHub means it is not followed.

func (*Client) GetProjectSettings

func (c *Client) GetProjectSettings(ctx context.Context, org, repo string) (*ProjectSettings, error)

GetProjectSettings returns the v2 project settings.

func (*Client) ListBranchPipelines added in v8.79.0

func (c *Client) ListBranchPipelines(ctx context.Context, org, repo, branch, pageToken string) (*PipelinePage, error)

ListBranchPipelines returns one page of the pipelines of branch, newest first: the most recent ones for an empty pageToken, the page after a page for its NextPageToken. The branch of a pull request from a fork is "pull/<number>". CircleCI lists pipelines by branch only; the caller picks the one of a revision from Pipeline.VCS.Revision.

func (*Client) ListCheckoutKeys

func (c *Client) ListCheckoutKeys(ctx context.Context, org, repo string) ([]CheckoutKey, error)

ListCheckoutKeys returns the project's checkout keys.

func (*Client) ListPipelineWorkflows

func (c *Client) ListPipelineWorkflows(ctx context.Context, pipelineID string) ([]Workflow, error)

ListPipelineWorkflows returns the workflows of a pipeline.

func (*Client) ListPipelines

func (c *Client) ListPipelines(ctx context.Context, org, repo, pageToken string) (*PipelinePage, error)

ListPipelines returns one page of the project's pipelines, newest first: the most recent ones for an empty pageToken, the page after a page for its NextPageToken.

func (*Client) ListWorkflowJobs

func (c *Client) ListWorkflowJobs(ctx context.Context, workflowID string) ([]Job, error)

ListWorkflowJobs returns the jobs of a workflow.

func (*Client) Me added in v8.64.4

func (c *Client) Me(ctx context.Context) (*User, error)

Me returns the token's user.

func (*Client) StopBuilding added in v8.64.8

func (c *Client) StopBuilding(ctx context.Context, org, repo string) error

StopBuilding stops the project org/repo from building (v1.1 "Stop building", DELETE …/enable): no pipeline runs for it from then on. The project stays readable — GET /api/v2/project answers as before, so GetProject cannot tell a stopped project from a building one.

func (*Client) Unfollow

func (c *Client) Unfollow(ctx context.Context, org, repo string) error

Unfollow makes the token's user unfollow org/repo (v1.1). The project stays, set up and building for the organization — see StopBuilding; what the unfollow changes is Following.

func (*Client) UpdateProjectSettings

func (c *Client) UpdateProjectSettings(ctx context.Context, org, repo string, settings ProjectSettings) (*ProjectSettings, error)

UpdateProjectSettings patches the settings set in settings and returns the settings as they are afterwards.

type Config

type Config struct {
	// Token is the CircleCI API token, sent as the Circle-Token header.
	Token string
	// BaseURL overrides the API host; empty means [DefaultBaseURL].
	BaseURL string
	// HTTPClient overrides the HTTP client; nil means one with a timeout.
	HTTPClient *http.Client
	// Logger receives one debug line per request; nil discards.
	Logger *logrus.Logger
}

Config configures a Client.

type Job

type Job struct {
	Name   string `json:"name"`
	Status string `json:"status"`
	Type   string `json:"type"`
}

Job is one job of a workflow.

type Pipeline

type Pipeline struct {
	ID        string      `json:"id"`
	Number    int64       `json:"number"`
	State     string      `json:"state"`
	CreatedAt time.Time   `json:"created_at"`
	VCS       PipelineVCS `json:"vcs"`
}

Pipeline is one pipeline of a project.

type PipelinePage added in v8.65.1

type PipelinePage struct {
	Items         []Pipeline `json:"items"`
	NextPageToken string     `json:"next_page_token"`
}

PipelinePage is one page of a project's pipelines, newest first, and the token of the page after it — empty on the last page.

type PipelineVCS

type PipelineVCS struct {
	Tag      string `json:"tag"`
	Branch   string `json:"branch"`
	Revision string `json:"revision"`
}

PipelineVCS is what a pipeline built.

type Project

type Project struct {
	Slug             string  `json:"slug"`
	Name             string  `json:"name"`
	ID               string  `json:"id"`
	OrganizationName string  `json:"organization_name"`
	VCSInfo          VCSInfo `json:"vcs_info"`
}

Project is a CircleCI project as the v2 API describes it.

type ProjectSettings

type ProjectSettings struct {
	Advanced AdvancedSettings `json:"advanced"`
}

ProjectSettings are the v2 project settings; only the advanced settings the engine manages are modelled. Pointer fields are omitted when nil, so a value can carry just the settings to change.

type User added in v8.64.4

type User struct {
	ID    string `json:"id"`
	Login string `json:"login"`
	Name  string `json:"name"`
}

User is the token's CircleCI user (GET /api/v2/me). For an account connected through GitHub, Login is the GitHub login: the user CircleCI follows a project as.

type VCSInfo

type VCSInfo struct {
	VCSURL        string `json:"vcs_url"`
	Provider      string `json:"provider"`
	DefaultBranch string `json:"default_branch"`
}

VCSInfo is the repository a project builds.

type Workflow

type Workflow struct {
	ID             string `json:"id"`
	Name           string `json:"name"`
	Status         string `json:"status"`
	PipelineNumber int64  `json:"pipeline_number"`
	// CreatedAt orders the runs of one workflow name: a rerun is a new
	// workflow with the same name in the same pipeline, and the newest counts.
	CreatedAt time.Time `json:"created_at"`
}

Workflow is one workflow of a pipeline. Status is one of success, running, not_run, failed, error, failing, on_hold, canceled, unauthorized.

func NewestWorkflows added in v8.81.0

func NewestWorkflows(runs []Workflow) []Workflow

NewestWorkflows keeps the newest run of every workflow name, sorted by name: a rerun (from failed or in full) is a second workflow of the same name in the same pipeline, and the one it replaces keeps its failed status for ever, so only the newest run of a name says where the pipeline stands.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL