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 (v1.1), the token's user, the project, its settings and checkout keys, its pipelines (paged) and their workflows and jobs (v2), a job's steps and their output (v1.1), a workflow's cancel and rerun (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. A reader without a token of its own reads a public project's pipelines, workflows and jobs anonymously (Config.Anonymous): CircleCI answers those reads for a public project without one, and a private project with 404.
Index ¶
- Constants
- func BaseURLFromAPIURL(apiURL string) string
- func IsAPI(err error) bool
- func IsForbidden(err error) bool
- func IsInvalidConfig(err error) bool
- func IsNotFound(err error) bool
- func JobFailed(status string) bool
- func PipelineContinuing(state string) bool
- func PipelineURL(org, repo string, number int64) string
- func ProjectSlug(org, repo string) string
- func PullRequestBranch(headRef string, fork bool, number int) string
- func SetupOnly(workflows []Workflow) bool
- func WorkflowFailed(status string) bool
- func WorkflowFinished(status string) bool
- func WorkflowRunning(status string) bool
- func WorkflowSucceeded(status string) bool
- func WorkflowURL(org, repo string, number int64, workflowID string) string
- type AdvancedSettings
- type CheckoutKey
- type Client
- func (c *Client) CancelWorkflow(ctx context.Context, workflowID string) error
- func (c *Client) CreateCheckoutKey(ctx context.Context, org, repo, keyType string) (*CheckoutKey, error)
- func (c *Client) FailedStepsOutput(ctx context.Context, org, repo string, number int64) (string, error)
- func (c *Client) FindPipelineByRevision(ctx context.Context, org, repo, branch, revision string) (*Pipeline, error)
- func (c *Client) FindPipelineByTag(ctx context.Context, org, repo, tag string) (*Pipeline, error)
- func (c *Client) Follow(ctx context.Context, org, repo string) error
- func (c *Client) Following(ctx context.Context, org, repo string) (bool, error)
- func (c *Client) GetPipeline(ctx context.Context, id string) (*PipelineDetail, error)
- func (c *Client) GetProject(ctx context.Context, org, repo string) (*Project, error)
- func (c *Client) GetProjectPipeline(ctx context.Context, org, repo string, number int64) (*PipelineDetail, error)
- func (c *Client) GetProjectSettings(ctx context.Context, org, repo string) (*ProjectSettings, error)
- func (c *Client) GetWorkflow(ctx context.Context, id string) (*WorkflowDetail, error)
- func (c *Client) JobSteps(ctx context.Context, org, repo string, number int64) ([]Step, error)
- func (c *Client) LastOutputAt(ctx context.Context, outputURL string) (time.Time, error)
- func (c *Client) ListBranchPipelines(ctx context.Context, org, repo, branch, pageToken string) (*PipelinePage, error)
- func (c *Client) ListCheckoutKeys(ctx context.Context, org, repo string) ([]CheckoutKey, error)
- func (c *Client) ListPipelineWorkflows(ctx context.Context, pipelineID string) ([]Workflow, error)
- func (c *Client) ListPipelines(ctx context.Context, org, repo, pageToken string) (*PipelinePage, error)
- func (c *Client) ListWorkflowJobs(ctx context.Context, workflowID string) ([]Job, error)
- func (c *Client) Me(ctx context.Context) (*User, error)
- func (c *Client) RerunWorkflow(ctx context.Context, workflowID string, fromFailed bool) (string, error)
- func (c *Client) RerunWorkflowFromFailed(ctx context.Context, workflowID string) (string, error)
- func (c *Client) TriggerTagPipeline(ctx context.Context, org, repo, tag string) (*Pipeline, error)
- func (c *Client) Unfollow(ctx context.Context, org, repo string) error
- func (c *Client) UpdateProjectSettings(ctx context.Context, org, repo string, settings ProjectSettings) (*ProjectSettings, error)
- type Config
- type Job
- type Pipeline
- type PipelineDetail
- type PipelinePage
- type PipelineVCS
- type Project
- type ProjectSettings
- type Step
- type User
- type VCSInfo
- type Workflow
- type WorkflowDetail
Constants ¶
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.
const DefaultBaseURL = "https://circleci.com"
DefaultBaseURL is CircleCI's public API host.
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.
const RevisionPipelinePages = 3
RevisionPipelinePages bounds the search of FindPipelineByRevision: the pipeline of a pull request's head is among its branch's newest.
const WorkflowTagSetup = "setup"
WorkflowTagSetup is the Workflow.Tag of a setup workflow.
Variables ¶
This section is empty.
Functions ¶
func BaseURLFromAPIURL ¶ added in v8.81.0
BaseURLFromAPIURL returns the Config.BaseURL for an API v2 URL: the URL without its /api/v2 suffix.
func IsForbidden ¶ added in v8.124.0
IsForbidden asserts forbiddenError: CircleCI answered 403 -- for a write, the token is read-only or its user may not write to the project.
func IsInvalidConfig ¶
IsInvalidConfig asserts invalidConfigError.
func IsNotFound ¶
IsNotFound asserts notFoundError: CircleCI answered 404 — for a project, the repository is not followed.
func PipelineContinuing ¶ added in v8.115.7
PipelineContinuing says whether a pipeline state is one of a setup pipeline whose configuration is not continued yet: its setup workflow queued or running (setup-pending, setup), or its continuation submitted and not created (pending). The workflows that carry the build do not exist yet; a settled pipeline reads created (or errored).
func PipelineURL ¶ added in v8.81.0
PipelineURL is the pipeline's page in the CircleCI UI.
func ProjectSlug ¶ added in v8.126.0
ProjectSlug is the slug CircleCI names the project of a GitHub repository by, the project_slug of its pipelines and workflows.
func PullRequestBranch ¶ added in v8.124.0
PullRequestBranch is the branch CircleCI builds a pull request's head as: the head's branch name, or "pull/<number>" for a head in a fork.
func SetupOnly ¶ added in v8.125.0
SetupOnly says whether workflows are a dynamic-config pipeline's setup workflow and nothing else: the continuation has not created the build's workflows yet, or CircleCI's listing lags behind them.
func WorkflowFailed ¶
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 WorkflowFinished ¶ added in v8.87.5
WorkflowFinished says whether a workflow status is final: a success or a terminal failure. A workflow that is not finished can still change, and so can what CircleCI answers about it -- its jobs are listed only once it has set them up.
func WorkflowRunning ¶ added in v8.81.0
WorkflowRunning says whether a workflow status is still moving.
func WorkflowSucceeded ¶
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 (*Client) CancelWorkflow ¶ added in v8.126.0
CancelWorkflow cancels a running workflow. CircleCI accepts the cancel and finishes the workflow on its own; the workflow reads canceled a little later. A token without write access is refused with IsForbidden.
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) FailedStepsOutput ¶ added in v8.107.0
func (c *Client) FailedStepsOutput(ctx context.Context, org, repo string, number int64) (string, error)
FailedStepsOutput returns the output of the failed steps of job number of org/repo (v1.1: API v2 has no job output), in step order. The output lives at a signed URL per step, read without the token.
func (*Client) FindPipelineByRevision ¶ added in v8.124.0
func (c *Client) FindPipelineByRevision(ctx context.Context, org, repo, branch, revision string) (*Pipeline, error)
FindPipelineByRevision returns the newest pipeline of branch that built revision, or nil when the branch's newest RevisionPipelinePages pages do not include one: CircleCI has not started it yet, or never will.
func (*Client) FindPipelineByTag ¶ added in v8.81.0
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 ¶
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
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) GetPipeline ¶ added in v8.126.0
GetPipeline returns the pipeline of id; IsNotFound when CircleCI knows none the token's user sees.
func (*Client) GetProject ¶
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) GetProjectPipeline ¶ added in v8.126.0
func (c *Client) GetProjectPipeline(ctx context.Context, org, repo string, number int64) (*PipelineDetail, error)
GetProjectPipeline returns pipeline number of org/repo, the number the CircleCI UI shows; IsNotFound when the project has none.
func (*Client) GetProjectSettings ¶
func (c *Client) GetProjectSettings(ctx context.Context, org, repo string) (*ProjectSettings, error)
GetProjectSettings returns the v2 project settings.
func (*Client) GetWorkflow ¶ added in v8.126.0
GetWorkflow returns the workflow of id; IsNotFound when CircleCI knows none the token's user sees.
func (*Client) JobSteps ¶ added in v8.126.0
JobSteps returns the steps of job number of org/repo, in order.
func (*Client) LastOutputAt ¶ added in v8.126.0
LastOutputAt reads a step's output at outputURL and returns the time of its last message: when the step last wrote anything. Zero when the step has written nothing yet.
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 ¶
ListCheckoutKeys returns the project's checkout keys.
func (*Client) ListPipelineWorkflows ¶
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 ¶
ListWorkflowJobs returns the jobs of a workflow.
func (*Client) RerunWorkflow ¶ added in v8.126.0
func (c *Client) RerunWorkflow(ctx context.Context, workflowID string, fromFailed bool) (string, error)
RerunWorkflow reruns a finished workflow and returns the id of the new workflow, a second workflow of the same name in the same pipeline: every job of it, or with fromFailed its failed jobs and the jobs that depend on them, the passed ones kept. A token without write access is refused with IsForbidden; a workflow CircleCI will not rerun (one still running, one without a failed job for fromFailed) with IsAPI carrying its message.
func (*Client) RerunWorkflowFromFailed ¶ added in v8.124.0
RerunWorkflowFromFailed reruns the failed jobs of a finished workflow and the jobs that depend on them, and returns the id of the new workflow: the rerun is a second workflow of the same name in the same pipeline. A token without write access is refused with IsForbidden.
func (*Client) TriggerTagPipeline ¶ added in v8.97.2
TriggerTagPipeline runs the project's pipeline for tag: the build of a tag pushed before CircleCI followed the project, which CircleCI never saw.
func (*Client) Unfollow ¶
Unfollow makes the token's user unfollow org/repo (v1.1). The project stays, set up and building for the organization; 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
// Anonymous is a client without a token: it reads what CircleCI answers
// without one, the pipelines, workflows and jobs of a public project (a
// private one answers 404, IsNotFound), and no header is sent. Set with
// an empty Token; a token and Anonymous together are a config error, as
// is neither, so a reader meant to hold a token does not read anonymously
// by accident.
Anonymous bool
// BaseURL overrides the API host; empty means [DefaultBaseURL].
BaseURL string
// HTTPClient overrides the HTTP client; nil means one with a timeout,
// sending through Transport.
HTTPClient *http.Client
// Transport sends the requests of the default HTTP client; nil means
// http.DefaultTransport. A caller counting the requests builds its
// counter here.
Transport http.RoundTripper
// Logger receives one debug line per request; nil discards.
Logger *logrus.Logger
}
Config configures a Client.
type Job ¶
type Job struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
Type string `json:"type"`
JobNumber int64 `json:"job_number"`
StartedAt time.Time `json:"started_at"`
StoppedAt time.Time `json:"stopped_at"`
}
Job is one job of a workflow. JobNumber is absent for an approval and for a job that has not started, and so are StartedAt (zero) and, while the job runs, StoppedAt.
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 PipelineDetail ¶ added in v8.126.0
PipelineDetail is one pipeline as the pipeline endpoints answer it: the pipeline and the project it belongs to.
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 Step ¶ added in v8.126.0
type Step struct {
Name string
Index int
Status string
StartedAt time.Time
EndedAt time.Time
// OutputURL is where the step's output is, a signed URL read without
// the token; empty for a step without output.
OutputURL string
}
Step is one step of a job as the v1.1 job detail lists it (API v2 has no steps): what the job is doing right now when it is running. A step that has not started has a zero StartedAt; one still running a zero EndedAt. A parallel step is listed once per action, Index telling them apart.
type User ¶ added in v8.64.4
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"`
// StoppedAt is when the workflow finished; zero while it runs.
StoppedAt time.Time `json:"stopped_at"`
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"`
// Tag is [WorkflowTagSetup] for the setup workflow of a dynamic-config
// pipeline, the one that continues the pipeline with the workflows that
// carry the build; empty for every other workflow.
Tag string `json:"tag"`
}
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
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.
type WorkflowDetail ¶ added in v8.126.0
type WorkflowDetail struct {
Workflow
PipelineID string `json:"pipeline_id"`
ProjectSlug string `json:"project_slug"`
}
WorkflowDetail is one workflow as the workflow endpoint answers it: the workflow, its pipeline and its project.