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 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
- func IsAPI(err error) bool
- func IsInvalidConfig(err error) bool
- func IsNotFound(err error) bool
- func WorkflowFailed(status string) bool
- func WorkflowSucceeded(status string) bool
- type AdvancedSettings
- type CheckoutKey
- type Client
- func (c *Client) CreateCheckoutKey(ctx context.Context, org, repo, keyType string) (*CheckoutKey, 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) GetProject(ctx context.Context, org, repo string) (*Project, error)
- func (c *Client) GetProjectSettings(ctx context.Context, org, repo string) (*ProjectSettings, 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 string) ([]Pipeline, error)
- func (c *Client) ListWorkflowJobs(ctx context.Context, workflowID string) ([]Job, error)
- func (c *Client) Me(ctx context.Context) (*User, error)
- func (c *Client) StopBuilding(ctx context.Context, org, repo string) error
- func (c *Client) TriggerPipeline(ctx context.Context, org, repo string, req TriggerRequest) (*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 PipelineVCS
- type Project
- type ProjectSettings
- type TriggerRequest
- type User
- type VCSInfo
- type Workflow
Constants ¶
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.
Variables ¶
This section is empty.
Functions ¶
func IsInvalidConfig ¶
IsInvalidConfig asserts invalidConfigError.
func IsNotFound ¶
IsNotFound asserts notFoundError: CircleCI answered 404 — for a project, the repository is not followed.
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 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) 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 ¶
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) 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) GetProjectSettings ¶
func (c *Client) GetProjectSettings(ctx context.Context, org, repo string) (*ProjectSettings, error)
GetProjectSettings returns the v2 project settings.
func (*Client) ListCheckoutKeys ¶
ListCheckoutKeys returns the project's checkout keys.
func (*Client) ListPipelineWorkflows ¶
ListPipelineWorkflows returns the workflows of a pipeline.
func (*Client) ListPipelines ¶
ListPipelines returns the project's most recent pipelines (the first page, newest first).
func (*Client) ListWorkflowJobs ¶
ListWorkflowJobs returns the jobs of a workflow.
func (*Client) StopBuilding ¶ added in v8.64.8
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 ¶
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 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
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.