circleciclient

package
v8.67.0 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 2026 License: Apache-2.0 Imports: 11 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 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 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 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 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) 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) 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) TriggerPipeline

func (c *Client) TriggerPipeline(ctx context.Context, org, repo string, req TriggerRequest) (*Pipeline, error)

TriggerPipeline triggers a pipeline for the tag or branch in req: the way a tag build the project missed (followed after the tag, renamed) is run.

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 TriggerRequest

type TriggerRequest struct {
	Tag    string `json:"tag,omitempty"`
	Branch string `json:"branch,omitempty"`
}

TriggerRequest names the revision a pipeline is triggered for: a tag or a branch, one of the two.

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"`
}

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

Jump to

Keyboard shortcuts

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