apiclient

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package apiclient provides a thin HTTP client for the CircleCI REST API.

Index

Constants

View Source 
const (
	ConnectionNextStepRedirect = "redirect"
	ConnectionNextStepRegister = "register"
)

Next steps a connection setup can call for. Redirect is the case the CLI can drive: CircleCI already has an app registered with the provider, so the user only has to approve it. Register means no app exists yet and one has to be registered from a manifest, which is a browser flow the CLI cannot complete.

View Source 
const (
	RollbackTypePipeline = "pipeline"
	RollbackTypeAgent    = "agent"
)

Rollback types reported by the rollback endpoint, naming what the returned ID identifies: a pipeline rollback is carried out by a triggered pipeline run, an agent rollback by a restore-version command the release agent picks up.

View Source 
const (
	PhaseCreated = "created"
	PhaseQueued  = "queued"
	PhaseStarted = "started"
	PhaseEnded   = "ended"
)

V3 lifecycle phases, as reported in the phase field of a run, workflow, job or step. The API is free to report others (it has its own vocabulary for the pre-start states); see PhaseNotStarted.

View Source 
const (
	StatusCanceled     = "canceled"
	StatusError        = "error"
	StatusFailed       = "failed"
	StatusFailing      = "failing"
	StatusNotRun       = "not_run"
	StatusOnHold       = "on_hold"
	StatusQueued       = "queued"
	StatusRunning      = "running"
	StatusSuccess      = "success"
	StatusUnauthorized = "unauthorized"
)

Pipeline status values, as reported by the V3 runs API and accepted by the pipeline.status search filter.

Variables

View Source 
var ErrDLCGone = errors.New("dlc: endpoint no longer available")

ErrDLCGone is returned by PurgeDLC when the endpoint responds 410 Gone, indicating the feature has been retired or the CLI needs upgrading.

View Source 
var ErrFunctionNotFound = errors.New("function not found")

ErrFunctionNotFound is returned when a function is not published, or is published under a name the discovery API does not list.

View Source 
var ErrNamespaceNotFound = errors.New("namespace not found")

ErrNamespaceNotFound is returned by GetNamespace when the namespace does not exist.

View Source 
var ErrNoRelease = errors.New("no release returned")

ErrNoRelease is returned by LatestRelease when the server answers 200 with an empty data array. The handler always emits exactly one item, so this should be impossible; callers treat it as a fetch failure rather than "no update".

View Source 
var ErrOrbCategoryNotFound = errors.New("orb category not found")

ErrOrbCategoryNotFound is returned when an orb category does not exist.

View Source 
var ErrOrbNotFound = errors.New("orb not found")

ErrOrbNotFound is returned when an orb package does not exist.

View Source 
var ErrOrbVersionNotFound = errors.New("orb version not found")

ErrOrbVersionNotFound is returned when an orb version does not exist.

View Source 
var ErrOrgNotFound = errors.New("organization not found")

ErrOrgNotFound is returned by ResolveOrgID when no org matches the slug.

View Source 
var ErrProjectNotFound = errors.New("project not found")

ErrProjectNotFound is returned by GetProjectBySlug when no project matches the slug.

View Source 
var ErrResourceClassNotFound = errors.New("resource class not found")

ErrResourceClassNotFound is returned by ResourceClassByName when no resource class matches the fully qualified resource class.

Functions

func BuildRunFilter 

func BuildRunFilter(branch, status string) string

BuildRunFilter constructs a filter expression for the V3 runs/search endpoint.

func ParseServerMessage 

func ParseServerMessage(body []byte) string

ParseServerMessage tries to extract a human-readable message from an error response body. It checks "error" and "message" JSON fields, falling back to the raw body string. Returns "" for an empty body.

func PhaseNotStarted added in v1.0.47401 

func PhaseNotStarted(phase string) bool

PhaseNotStarted reports whether a phase means the work has not begun: the "created" and "queued" phases, and — deliberately — any phase this client does not recognise. Only "started" and "ended" describe work that has produced something to look at, so an unfamiliar phase is presumed to be another pre-start state rather than a synonym for one of those two. An unrecognised phase has no glyph of its own (PhaseOutcomeSymbol falls back to a neutral bullet, easily read as "running"), so the caller needs to be able to tell it apart from a job that is genuinely running.

func PhaseOutcomeStatus 

func PhaseOutcomeStatus(phase, outcome, currentOutcome string) string

PhaseOutcomeStatus derives a human-readable status string from V3 phase, outcome, and current_outcome fields, prefixed with a status emoji. The emoji is a real Unicode glyph (e.g. "✅ succeeded"), not a ":shortcode:", so it renders whether or not the output is passed through glamour — piped and CI output show the emoji rather than a literal ":white_check_mark:". Contexts that lay out raw fixed-width columns (the interactive pickers, run watch) should use PhaseOutcomeSymbol/PhaseOutcomeText instead, since a width-2 emoji throws off "%-Ns" padding.

func PhaseOutcomeSymbol 

func PhaseOutcomeSymbol(phase, outcome, currentOutcome string) string

PhaseOutcomeSymbol is like PhaseOutcomeStatus but returns a single plain, single-width Unicode glyph (e.g. "✓") rather than a status emoji. Use it in raw fixed-width layouts — the interactive list pickers, run watch — where the width-2 emoji from PhaseOutcomeStatus would throw off column padding.

func PhaseOutcomeText 

func PhaseOutcomeText(phase, outcome, currentOutcome string) string

PhaseOutcomeText is PhaseOutcomeStatus without the leading emoji — the plain status word (e.g. "running", "not run", "succeeded"). Use it in raw fixed-width layouts (the interactive list pickers, run watch) where a width-2 status emoji would misalign the columns, pairing it with PhaseOutcomeSymbol for a plain single-width glyph.

func StatusPhaseOutcome 

func StatusPhaseOutcome(status string) (phase, currentOutcome string)

StatusPhaseOutcome maps a pipeline.status value (the tokens above, as used by the runs/search pipeline.status filter and the run picker's status cycle) to the run phase and current_outcome the my-runs list endpoint filters on (filter[phase], filter[current_outcome]). An empty status — or an unknown one — yields two empty strings, which filterParam then omits (no status filter).

The pipeline status is an aggregate; a run carries phase ∈ {created, queued, started, ended} and current_outcome. Terminal statuses are an "ended" phase with the matching outcome; in-progress statuses are the "started" (or "queued") phase, narrowed by current_outcome only where one distinguishes them (a partially-failed run is "started"/"failed" → "failing"; a plainly-running one is just "started").

Types

type Actor 

type Actor struct {
	Login     string `json:"login"`
	AvatarURL string `json:"avatar_url"`
}

Actor is a CircleCI user or token.

type Artifact 

type Artifact struct {
	Path      string `json:"path"`
	URL       string `json:"url"`
	Execution int    `json:"execution"`
}

Artifact is a file produced by a CircleCI job.

type Client 

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

Client is a CircleCI API client. It is authenticated when Config.Token was set; see Authenticated.

func New 

func New(cfg Config) *Client

New creates a Client. baseURL should be the CircleCI host, e.g. "https://circleci.com". An http.RoundTripper can be injected for testing. Set CIRCLE_DEBUG=1 to log all HTTP requests and response status codes to stderr.

func (*Client) AddOrbToCategory 

func (c *Client) AddOrbToCategory(ctx context.Context, orbID, categoryID string) error

AddOrbToCategory adds an orb to a category.

func (*Client) Authenticated added in v1.0.47027 

func (c *Client) Authenticated() bool

Authenticated reports whether the client carries an API token.

func (*Client) CancelWorkflow 

func (c *Client) CancelWorkflow(ctx context.Context, id uuid.UUID) error

CancelWorkflow requests cancellation of a running workflow. Cancellation is processed asynchronously; the V3 API acknowledges with the workflow id.

func (*Client) Compile added in v1.0.47692 

func (c *Client) Compile(ctx context.Context, in CompileInput) (*CompileResult, error)

Compile compiles a pipeline config via POST /api/v3/configs/compile and reports whether it is valid, along with the fully expanded YAML. `config validate` and `config process` are the same operation — compilation — and differ only in which fields of the result they read.

Transport and request-level failures are returned as errors; a config that merely fails to compile comes back as a CompileResult with Valid false.

func (*Client) ContextDetailFor added in v1.0.49698 

func (c *Client) ContextDetailFor(ctx context.Context, ctxt *Context) (*ContextDetail, error)

ContextDetailFor completes a context the caller already holds, fetching only its environment variables and restrictions — concurrently, as above.

Prefer this to GetContextDetail whenever the context is already in hand. Resolving a name through ListContexts yields the context itself, so re-fetching it by id costs a round trip for nothing. The list carries no references, so callers that resolved by name should set OrgID from the org they filtered on.

func (*Client) CreateContext 

func (c *Client) CreateContext(ctx context.Context, name string, orgID uuid.UUID) (*Context, error)

CreateContext creates a context owned by orgID.

func (*Client) CreateContextRestriction 

func (c *Client) CreateContextRestriction(
	ctx context.Context, contextID uuid.UUID, restrictionType, matchPattern string,
) (*ContextRestriction, error)

CreateContextRestriction adds a restriction to a context. restrictionType is "project", "expression" or "group"; matchPattern is a project UUID, a pipeline expression, or a group UUID to match. Passing the organization's own id as a group grants all members.

func (*Client) CreateIOSSigningConfig 

func (c *Client) CreateIOSSigningConfig(ctx context.Context, orgID uuid.UUID, name string, certID uuid.UUID, profiles []IOSProvisioningProfile) (uuid.UUID, error)

CreateIOSSigningConfig creates a signing config linking a certificate to one or more base64-encoded provisioning profiles. Returns the new config ID.

func (*Client) CreateNamespace 

func (c *Client) CreateNamespace(ctx context.Context, req CreateNamespaceRequest) (*Namespace, error)

CreateNamespace creates a namespace for the given organization ID.

func (*Client) CreateOrbPackage 

func (c *Client) CreateOrbPackage(ctx context.Context, req CreateOrbPackageRequest) (*OrbPackage, error)

CreateOrbPackage creates a new orb package.

func (*Client) CreateOrg 

func (c *Client) CreateOrg(ctx context.Context, name, vcsType string) (*OrgInfo, error)

CreateOrg creates a new organization. vcsType must be one of "github", "bitbucket", or "circleci".

func (*Client) CreatePipelineDefinition 

func (c *Client) CreatePipelineDefinition(ctx context.Context, projectID string, input CreatePipelineDefinitionInput) (*PipelineDefinition, error)

CreatePipelineDefinition creates a new pipeline definition for a project via POST /api/v3/pipelines. The owning project travels in the body's references rather than the path.

func (*Client) CreatePolicyBundle 

func (c *Client) CreatePolicyBundle(ctx context.Context, ownerID, policyCtx string, policies PolicyBundle, dryRun bool) (json.RawMessage, error)

CreatePolicyBundle uploads a policy bundle. When dryRun is true it performs a diff-only check without applying changes.

func (*Client) CreateProject 

func (c *Client) CreateProject(ctx context.Context, vcs, org, name string) (*ProjectInfo, error)

CreateProject creates a new project in the given organization. vcs is the VCS provider (e.g. "github", "circleci"). org is the organization slug or UUID. name is the project name.

func (*Client) CreateResourceClass 

func (c *Client) CreateResourceClass(ctx context.Context, orgID uuid.UUID, resourceClass, description string) (*ResourceClass, error)

CreateResourceClass creates a new runner resource class owned by orgID.

func (*Client) CreateRunnerTokenV3 added in v1.0.50624 

func (c *Client) CreateRunnerTokenV3(ctx context.Context, rcID uuid.UUID, nickname string) (*RunnerToken, error)

CreateRunnerTokenV3 creates a new token for the given resource class UUID using the V3 /runner/tokens endpoint. The ResourceClass field is the namespace/name the response references.

func (*Client) CreateTrigger 

func (c *Client) CreateTrigger(ctx context.Context, input CreateTriggerInput) (*Trigger, error)

CreateTrigger creates a new trigger for a project's pipeline definition via POST /api/v3/triggers. filter[project_id] is sent so triggers on a project's synthetic OAuth pipeline — whose id resolves to no stored row — can be created too.

func (*Client) DeleteContext 

func (c *Client) DeleteContext(ctx context.Context, id uuid.UUID) error

DeleteContext deletes a context by its UUID.

func (*Client) DeleteContextEnvVar 

func (c *Client) DeleteContextEnvVar(ctx context.Context, contextID uuid.UUID, name string) error

DeleteContextEnvVar removes an environment variable from a context. The name is a query filter rather than a path segment, which is what the endpoint expects.

func (*Client) DeleteContextRestriction 

func (c *Client) DeleteContextRestriction(ctx context.Context, contextID, restrictionID uuid.UUID) error

DeleteContextRestriction removes a restriction from a context. Both ids are required: the restriction is addressed by path, but the endpoint also demands the owning context as a filter, which is what it authorises against.

func (*Client) DeleteEnvVar 

func (c *Client) DeleteEnvVar(ctx context.Context, projectSlug, name string) error

DeleteEnvVar deletes a project environment variable by name.

func (*Client) DeleteIOSCertificate 

func (c *Client) DeleteIOSCertificate(ctx context.Context, certID uuid.UUID) error

DeleteIOSCertificate deletes a certificate by ID. The server returns 409 Conflict if the certificate is referenced by one or more signing configs.

func (*Client) DeleteIOSSigningConfig 

func (c *Client) DeleteIOSSigningConfig(ctx context.Context, id uuid.UUID) error

DeleteIOSSigningConfig deletes a signing config by ID. The server returns 204 No Content on success.

func (*Client) DeleteNamespace 

func (c *Client) DeleteNamespace(ctx context.Context, name string) error

DeleteNamespace deletes a namespace and all its orbs. The name is resolved to an ID first.

func (*Client) DeleteResourceClass 

func (c *Client) DeleteResourceClass(ctx context.Context, id uuid.UUID, force bool) error

DeleteResourceClass deletes a runner resource class by its id. With force, any tokens issued for it are deleted too; without it, the server rejects the delete (409) if tokens still exist.

func (*Client) DeleteRunnerTokenV3 added in v1.0.50624 

func (c *Client) DeleteRunnerTokenV3(ctx context.Context, tokenID uuid.UUID) error

DeleteRunnerTokenV3 deletes a runner token by its ID using the V3 /runner/tokens endpoint.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method, path string, opts ...func(*httpcl.Request)) (int, error)

Do makes a raw authenticated request to the CircleCI API and returns the HTTP status code and raw response body. It is intended for the "circleci api" escape-hatch command and should not be used by typed command packages.

path must be an absolute path including the API version prefix (e.g. "/api/v2/project/..."). The Authorization: Bearer header is added automatically; callers may supply additional headers via extraHeaders.

Non-2xx status codes do NOT return an error — the caller is responsible for inspecting the status code and formatting the output accordingly.

func (*Client) DownloadArtifact 

func (c *Client) DownloadArtifact(ctx context.Context, artifactURL string, dst io.Writer) error

DownloadArtifact fetches an artifact URL (authenticated) and writes its contents to dst. The URL is a full absolute URL, not a base-relative path.

func (*Client) FetchPolicyBundle 

func (c *Client) FetchPolicyBundle(ctx context.Context, ownerID, policyCtx string) (json.RawMessage, error)

FetchPolicyBundle downloads the full bundle or a single named policy. Pass an empty policyName to fetch the entire bundle.

func (*Client) FetchPolicyBundleWithName 

func (c *Client) FetchPolicyBundleWithName(ctx context.Context, ownerID, policyCtx, policyName string) (json.RawMessage, error)

func (*Client) FollowProject 

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

FollowProject follows a project identified by its VCS type, org, and repo.

func (*Client) GetComponent added in v1.0.47471 

func (c *Client) GetComponent(ctx context.Context, componentID string) (*V3Component, error)

GetComponent returns a single deploy component by ID.

func (*Client) GetContext 

func (c *Client) GetContext(ctx context.Context, id uuid.UUID) (*Context, error)

GetContext returns a context by its UUID. The response covers the context and its group restrictions only; use GetContextDetail for env vars and the remaining restrictions.

func (*Client) GetContextDetail added in v1.0.49698 

func (c *Client) GetContextDetail(ctx context.Context, id uuid.UUID) (*ContextDetail, error)

GetContextDetail returns a context with its environment variables and all of its restrictions.

The three reads are independent, so they run concurrently: done in series this would cost three round trips to answer one `context get`. The first failure wins and cancels the rest, which is why each goroutine writes to its own variable and nothing is assembled until Wait returns.

func (*Client) GetDecisionLog 

func (c *Client) GetDecisionLog(ctx context.Context, ownerID, policyCtx, decisionID string, policyBundleOnly bool) (json.RawMessage, error)

GetDecisionLog returns a single decision log by ID. When policyBundleOnly is true, returns only the policy bundle snapshot.

func (*Client) GetDecisionLogs 

func (c *Client) GetDecisionLogs(ctx context.Context, ownerID, policyCtx string, req DecisionLogsRequest) ([]json.RawMessage, error)

GetDecisionLogs returns one page of policy decision logs. The caller is responsible for pagination (increment Offset until an empty slice is returned).

func (*Client) GetDeploySettings added in v1.0.47471 

func (c *Client) GetDeploySettings(ctx context.Context, projectID string) (*V3DeploySettings, error)

GetDeploySettings returns deploy settings for a project.

func (*Client) GetEnvironment added in v1.0.47471 

func (c *Client) GetEnvironment(ctx context.Context, envID string) (*V3Environment, error)

GetEnvironment returns a single deploy environment by ID.

func (*Client) GetFunctionByName added in v1.0.52018 

func (c *Client) GetFunctionByName(ctx context.Context, name string) (*Function, error)

GetFunctionByName resolves a function by its VCS-style name. An unknown name, and any name the API does not consider discoverable, comes back as an empty collection rather than a 404.

func (*Client) GetFunctionVersion added in v1.0.52018 

func (c *Client) GetFunctionVersion(ctx context.Context, id uuid.UUID) (*FunctionDescriptor, error)

GetFunctionVersion gets a version's descriptor. The id must come from a function's references: ids are assigned by the API and one built any other way will not resolve.

func (*Client) GetJobArtifactsV3 

func (c *Client) GetJobArtifactsV3(ctx context.Context, jobID string) ([]Artifact, error)

GetJobArtifactsV3 returns the artifacts for a job identified by UUID, using the V3 API.

func (*Client) GetJobResourceUsage added in v1.0.48122 

func (c *Client) GetJobResourceUsage(ctx context.Context, id uuid.UUID) (*JobResourceUsage, error)

GetJobResourceUsage fetches a job's sampled resource usage by UUID. The endpoint 404s for a job that never ran an executor — an approval job, or one that was cancelled before it started — so a not-found error here does not necessarily mean the job itself is missing.

func (*Client) GetJobStderr 

func (c *Client) GetJobStderr(ctx context.Context, jobID uuid.UUID, execution, stepNum int) ([]byte, error)

func (*Client) GetJobStdout 

func (c *Client) GetJobStdout(ctx context.Context, jobID uuid.UUID, execution, stepNum int) ([]byte, error)

func (*Client) GetJobStdoutCondensed 

func (c *Client) GetJobStdoutCondensed(ctx context.Context, jobID uuid.UUID, execution, stepNum int) ([]byte, error)

GetJobStdoutCondensed fetches a step's stdout condensed to its most error-relevant lines (noisy/repetitive output filtered out server-side). The endpoint returns raw text (octet-stream).

func (*Client) GetJobStdoutRange 

func (c *Client) GetJobStdoutRange(ctx context.Context, jobID uuid.UUID, execution, stepNum int, offset int64) (data []byte, terminal bool, err error)

GetJobStdoutRange fetches a step's stdout starting at byte offset, returning the bytes from that offset and whether stdout has finished — the API reports completion via the "X-Terminal: true" response header. Pass offset 0 for the first read and the number of bytes already consumed thereafter to resume (sent as "Range: bytes=<offset>-"). Bytes are returned raw, with ANSI styling intact, for colored display in a pager.

func (*Client) GetJobV3 

func (c *Client) GetJobV3(ctx context.Context, id uuid.UUID) (*JobV3, error)

GetJobV3 fetches job detail from the V3 API by UUID.

func (*Client) GetMe 

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

func (*Client) GetNamespace 

func (c *Client) GetNamespace(ctx context.Context, name string) (*Namespace, error)

GetNamespace looks up a namespace by name and returns its ID and name.

func (*Client) GetOrbCategoryByName 

func (c *Client) GetOrbCategoryByName(ctx context.Context, name string) (*OrbCategory, error)

GetOrbCategoryByName finds a category by exact name.

func (*Client) GetOrbPackageByID 

func (c *Client) GetOrbPackageByID(ctx context.Context, id uuid.UUID) (*OrbPackage, error)

GetOrbPackageByID gets a single orb package by UUID.

func (*Client) GetOrbPackageByName 

func (c *Client) GetOrbPackageByName(ctx context.Context, fullName string) (*OrbPackage, error)

GetOrbPackageByName resolves an orb by its full name (e.g. "ns/name"). It first resolves the namespace, then filters orbs by name.

func (*Client) GetOrbSource 

func (c *Client) GetOrbSource(ctx context.Context, id string) (string, error)

func (*Client) GetOrbVersionByID 

func (c *Client) GetOrbVersionByID(ctx context.Context, id string) (*OrbVersion, error)

GetOrbVersionByID gets a single orb version by UUID (includes source YAML).

func (*Client) GetOrbVersionByRef 

func (c *Client) GetOrbVersionByRef(ctx context.Context, ref string) (*OrbVersion, error)

GetOrbVersionByRef gets an orb version by its full ref (e.g. "ns/name@1.2.3" or "ns/name@volatile").

func (*Client) GetOrgSettings 

func (c *Client) GetOrgSettings(ctx context.Context, orgID uuid.UUID) (*OrgSettingsAttributes, error)

GetOrgSettings returns settings for an organization via GET /api/v3/orgs/:id/settings.

func (*Client) GetPipeline 

func (c *Client) GetPipeline(ctx context.Context, id string) (*Pipeline, error)

GetPipeline fetches a single pipeline by its UUID.

func (*Client) GetPipelineByNumber 

func (c *Client) GetPipelineByNumber(ctx context.Context, projectSlug string, number int64) (*Pipeline, error)

GetPipelineByNumber fetches a pipeline by its project-scoped number.

func (*Client) GetPolicySettings 

func (c *Client) GetPolicySettings(ctx context.Context, ownerID, policyCtx string) (DecisionSettings, error)

GetPolicySettings retrieves whether policy enforcement is enabled.

func (*Client) GetProjectByID 

func (c *Client) GetProjectByID(ctx context.Context, id uuid.UUID) (*ProjectRef, error)

GetProjectByID resolves a project UUID to its name (and owning org UUID) via GET /api/v3/projects/:id. Use this to label runs when only the project UUID is known — e.g. the cross-project "my runs" listing, where runs span projects whose slugs were never resolved.

func (*Client) GetProjectByName added in v1.0.48773 

func (c *Client) GetProjectByName(ctx context.Context, orgID, name string) (*ProjectRef, error)

GetProjectByName resolves a project by its name within an organization via GET /api/v3/projects. orgID must be the organization UUID.

Use this where a name is all that is known — a project whose slug carries opaque IDs cannot be addressed by slug, so its name is the only handle a user (or a previous run of the same command) supplies.

func (*Client) GetProjectBySlug 

func (c *Client) GetProjectBySlug(ctx context.Context, slug string) (*ProjectRef, error)

GetProjectBySlug resolves a project slug (vcs/org/repo) to its UUID, name, and owning org UUID via GET /api/v3/projects?filter[slug]=. Use this for the slug-to-UUID lookup; GetProjectInfo (v2) returns the fuller settings payload.

The endpoint is a collection: a slug matching no project returns an empty list (not a 404), which is surfaced as ErrProjectNotFound.

func (*Client) GetProjectInfo 

func (c *Client) GetProjectInfo(ctx context.Context, projectSlug string) (*ProjectInfo, error)

GetProjectInfo returns detailed information about a project by slug.

func (*Client) GetProjectSettings 

func (c *Client) GetProjectSettings(ctx context.Context, projectID uuid.UUID) (*ProjectSettingsAttributes, error)

GetProjectSettings returns settings for a project via GET /api/v3/projects/:id/settings.

func (*Client) GetResourceClass added in v1.0.51911 

func (c *Client) GetResourceClass(ctx context.Context, resourceClass string) (*ResourceClass, error)

GetResourceClass looks up a single resource class by its fully qualified namespace/name form via the v3 filter[resource_class] parameter. Returns ErrResourceClassNotFound when the class does not exist or belongs to an organization the caller cannot view.

func (*Client) GetResourceClassByID added in v1.0.51453 

func (c *Client) GetResourceClassByID(ctx context.Context, id uuid.UUID) (*ResourceClass, error)

GetResourceClassByID looks up a single resource class by its UUID via the v3 /runner/resource-classes/{id} endpoint. Returns ErrResourceClassNotFound when the server answers 404.

func (*Client) GetRunV3 

func (c *Client) GetRunV3(ctx context.Context, id uuid.UUID) (*RunV3, error)

GetRunV3 fetches a single run by UUID from the V3 API.

func (*Client) GetRunWorkflowsV3 

func (c *Client) GetRunWorkflowsV3(ctx context.Context, runID uuid.UUID) ([]WorkflowV3, error)

GetRunWorkflowsV3 fetches workflows for a run from the V3 API.

func (*Client) GetWorkflowJobsV3 

func (c *Client) GetWorkflowJobsV3(ctx context.Context, workflowID uuid.UUID) ([]WorkflowJobV3, error)

GetWorkflowJobsV3 returns all jobs for a workflow via the V3 API.

func (*Client) GetWorkflowV3 

func (c *Client) GetWorkflowV3(ctx context.Context, id uuid.UUID) (*WorkflowV3, error)

GetWorkflowV3 fetches a single workflow by UUID from the V3 API.

func (*Client) LatestRelease added in v1.0.47519 

func (c *Client) LatestRelease(ctx context.Context, tool string) (*Release, error)

LatestRelease returns the latest released version of the named tool via GET /api/v3/tool/releases?filter[tool]=<tool>.

tool is the tool's GitHub repository name (e.g. "circleci-cli"). The endpoint models a required-filter single lookup as a one-element collection, so the response is unwrapped from data[0].attributes. Non-2xx statuses surface as the underlying *httpcl.HTTPError so callers can distinguish transient (503) from permanent (400/401/403) failures.

func (*Client) ListCollaborations 

func (c *Client) ListCollaborations(ctx context.Context) ([]Collaboration, error)

ListCollaborations returns the organizations the authenticated user belongs to.

func (*Client) ListComponentVersions added in v1.0.47471 

func (c *Client) ListComponentVersions(ctx context.Context, componentID, envID string, limit int) ([]V3ComponentVersion, error)

ListComponentVersions returns versions of a component, optionally filtered by environment. Pass limit <= 0 for no limit (fetches all pages).

func (*Client) ListComponents added in v1.0.47471 

func (c *Client) ListComponents(ctx context.Context, orgID, projectID string, limit int) ([]V3Component, error)

ListComponents returns deploy components for an org, optionally filtered by project. Pass limit <= 0 for no limit (fetches all pages).

func (*Client) ListContextEnvVars 

func (c *Client) ListContextEnvVars(ctx context.Context, contextID uuid.UUID) ([]ContextEnvVar, error)

ListContextEnvVars returns the environment variables stored in a context. Values are never returned by the API; see ContextEnvVar.TruncatedValue.

func (*Client) ListContextRestrictions added in v1.0.49698 

func (c *Client) ListContextRestrictions(ctx context.Context, contextID uuid.UUID) ([]ContextRestriction, error)

ListContextRestrictions returns all of a context's restrictions — group, project and expression. It is the only source of group access; the context endpoints do not report it.

func (*Client) ListContexts 

func (c *Client) ListContexts(ctx context.Context, orgID uuid.UUID, name string) ([]Context, error)

ListContexts returns all contexts owned by orgID, via GET /api/v3/contexts?filter[org_id]=. Paginates automatically.

A non-empty name is sent as filter[name], which the API matches upstream as a case-insensitive substring — so it narrows pagination rather than just the final page. An empty name is omitted entirely.

func (*Client) ListDeployments added in v1.0.47331 

func (c *Client) ListDeployments(ctx context.Context, orgID, projectID string, limit int) ([]V3Deployment, error)

ListDeployments returns up to limit deployments for an org, optionally filtered by project. Pass limit <= 0 for no limit (fetches all pages).

func (*Client) ListEnvVars 

func (c *Client) ListEnvVars(ctx context.Context, projectSlug string) ([]EnvVar, error)

ListEnvVars returns the environment variables for a project. Values are masked in the response.

func (*Client) ListEnvironments added in v1.0.47471 

func (c *Client) ListEnvironments(ctx context.Context, orgID string, limit int) ([]V3Environment, error)

ListEnvironments returns deploy environments for an org. Pass limit <= 0 for no limit (fetches all pages).

func (*Client) ListFunctions added in v1.0.51515 

func (c *Client) ListFunctions(ctx context.Context) ([]*Function, error)

ListFunctions lists every discoverable published function, following the cursor until the whole collection has been read.

func (*Client) ListIOSCertificates 

func (c *Client) ListIOSCertificates(ctx context.Context, orgID uuid.UUID) ([]IOSCertificate, error)

ListIOSCertificates returns the certificates stored for the given org.

func (*Client) ListIOSSigningConfigs 

func (c *Client) ListIOSSigningConfigs(ctx context.Context, orgID uuid.UUID) ([]IOSSigningConfig, error)

ListIOSSigningConfigs returns the signing configs stored for the given org.

func (*Client) ListMyRunsV3 

func (c *Client) ListMyRunsV3(ctx context.Context, params MyRunsParams) ([]RunV3, error)

ListMyRunsV3 lists runs triggered by the authenticated user across all projects, via GET /api/v3/runs?filter[user_id]=me. Paginates transparently when params.Limit exceeds maxRunsPageSize.

Unlike the runs/search endpoint, this endpoint has no pipeline.status filter — it filters on the run's own phase and current_outcome — so the status is converted to those via StatusPhaseOutcome.

func (*Client) ListOrbCategories 

func (c *Client) ListOrbCategories(ctx context.Context) ([]*OrbCategory, error)

ListOrbCategories lists all orb categories, depaginating automatically.

func (*Client) ListOrbPackages 

func (c *Client) ListOrbPackages(ctx context.Context, namespaceID string, uncertified, private bool) ([]*OrbPackage, error)

ListOrbPackages lists all orb packages, depaginating automatically. namespaceID filters by namespace (empty = global). When uncertified is false, only certified orbs are returned.

func (*Client) ListOrbVersions 

func (c *Client) ListOrbVersions(ctx context.Context, orbID, channel string) ([]*OrbVersion, error)

ListOrbVersions lists all versions for an orb, depaginating automatically. channel can be "stable", "dev", or "" for all.

func (*Client) ListOrgs added in v1.0.50034 

func (c *Client) ListOrgs(ctx context.Context) ([]Organization, error)

ListOrgs returns every organization the authenticated user belongs to, via GET /api/v3/orgs. Paginates automatically.

The response carries no slug, and one cannot be derived: only a VCS-backed org has a slug at all, so an org is identified here by its UUID.

func (*Client) ListPipelineDefinitions 

func (c *Client) ListPipelineDefinitions(ctx context.Context, projectID string) ([]PipelineDefinition, error)

ListPipelineDefinitions returns all pipeline definitions for a project via GET /api/v3/pipelines.

func (*Client) ListProjects 

func (c *Client) ListProjects(ctx context.Context, filter ProjectFilter) ([]ProjectSummary, error)

ListProjects returns the projects matching filter, via GET /api/v3/projects. Paginates automatically.

Matching is the API's job: filter[name] is a case-insensitive search applied upstream, so it narrows pagination rather than just the final page.

func (*Client) ListProviderConnections added in v1.0.48454 

func (c *Client) ListProviderConnections(ctx context.Context, orgID string) ([]ProviderConnection, error)

ListProviderConnections returns the organization's provider connections. orgID must be the organization UUID. An organization with no connections yields an empty slice, so an error means the check itself failed rather than that nothing is connected.

func (*Client) ListProviderRepositories added in v1.0.48658 

func (c *Client) ListProviderRepositories(
	ctx context.Context, orgID, provider, cursor string, limit int,
) ([]ProviderRepository, string, error)

ListProviderRepositories returns one page of the repositories an organization's connection to provider can reach, along with the cursor for the next page. An empty next cursor means the page returned was the last one.

orgID must be the organization UUID. limit caps the page size; the server's maximum is 100. A cursor encodes the limit it was minted with, so pass either a cursor or a limit, not both.

func (*Client) ListResourceClassesByClass added in v1.0.51832 

func (c *Client) ListResourceClassesByClass(ctx context.Context, resourceClass string) ([]ResourceClass, error)

ListResourceClassesByClass returns the single resource class named by its namespace/name via the v3 filter[resource_class] endpoint. The server answers 404 when the class does not exist or the caller cannot view it.

func (*Client) ListResourceClassesByNamespace 

func (c *Client) ListResourceClassesByNamespace(ctx context.Context, namespace string) ([]ResourceClass, error)

ListResourceClassesByNamespace returns every resource class in a namespace via the v3 filter[namespace] endpoint.

func (*Client) ListResourceClassesByOrg 

func (c *Client) ListResourceClassesByOrg(ctx context.Context, orgID uuid.UUID) ([]ResourceClass, error)

ListResourceClassesByOrg returns the resource classes for an organization, identified by its UUID, via the v3 filter[org_id] endpoint.

func (*Client) ListRunnerAgentsByNamespace added in v1.0.51336 

func (c *Client) ListRunnerAgentsByNamespace(ctx context.Context, namespace string) ([]RunnerAgent, error)

ListRunnerAgentsByNamespace returns every connected agent across a namespace's resource classes.

func (*Client) ListRunnerAgentsByOrg added in v1.0.51336 

func (c *Client) ListRunnerAgentsByOrg(ctx context.Context, orgID uuid.UUID) ([]RunnerAgent, error)

ListRunnerAgentsByOrg returns every connected agent in an organization.

func (*Client) ListRunnerAgentsByResourceClass added in v1.0.51336 

func (c *Client) ListRunnerAgentsByResourceClass(ctx context.Context, resourceClass string) ([]RunnerAgent, error)

ListRunnerAgentsByResourceClass returns every connected agent of one resource class, named by its fully qualified namespace/name resource class.

func (*Client) ListRunnerTokensByResourceClass added in v1.2.0 

func (c *Client) ListRunnerTokensByResourceClass(ctx context.Context, resourceClass string) ([]RunnerToken, error)

ListRunnerTokensByResourceClass returns tokens for the resource class named by its fully qualified namespace/name.

func (*Client) ListRunnerTokensByResourceClassID added in v1.2.0 

func (c *Client) ListRunnerTokensByResourceClassID(ctx context.Context, rcID uuid.UUID) ([]RunnerToken, error)

ListRunnerTokensByResourceClassID returns tokens for the resource class with the given UUID.

func (*Client) ListTriggers 

func (c *Client) ListTriggers(ctx context.Context, projectID, pipelineDefinitionID string) ([]Trigger, error)

ListTriggers returns all triggers for a project's pipeline definition via GET /api/v3/triggers. Both filters are sent so a trigger has to belong to the project as well as the pipeline, matching the old project-scoped route.

func (*Client) MakeDecision 

func (c *Client) MakeDecision(ctx context.Context, ownerID, policyCtx string, input string, metadata map[string]any) (json.RawMessage, error)

MakeDecision evaluates input against remote policies for the given owner and context.

func (*Client) PromoteOrbVersion 

func (c *Client) PromoteOrbVersion(ctx context.Context, versionID, segment string) (*OrbVersion, error)

PromoteOrbVersion promotes a dev orb version to a stable semver. segment must be "major", "minor", or "patch".

func (*Client) PublishOrbVersion 

func (c *Client) PublishOrbVersion(ctx context.Context, req PublishOrbVersionRequest) (*OrbVersion, error)

PublishOrbVersion publishes a new orb version.

func (*Client) PurgeDLC 

func (c *Client) PurgeDLC(ctx context.Context, projectID string) error

PurgeDLC purges the Docker Layer Cache for the given project ID.

func (*Client) RemoveIOSSigningConfigProfile added in v1.0.47993 

func (c *Client) RemoveIOSSigningConfigProfile(ctx context.Context, configID, profileID uuid.UUID) error

RemoveIOSSigningConfigProfile removes a provisioning profile from an existing signing config by profile ID. Removing an already-absent profile is a no-op.

func (*Client) RemoveOrbFromCategory 

func (c *Client) RemoveOrbFromCategory(ctx context.Context, orbID, categoryID string) error

RemoveOrbFromCategory removes an orb from a category.

func (*Client) RenameNamespace 

func (c *Client) RenameNamespace(ctx context.Context, req RenameNamespaceRequest) (*Namespace, error)

RenameNamespace renames a namespace. The current name is resolved to an ID first.

func (*Client) RerunWorkflow 

func (c *Client) RerunWorkflow(ctx context.Context, id string, fromFailed bool) (string, error)

RerunWorkflow triggers a rerun of the given workflow. When fromFailed is true only the failed jobs are rerun; otherwise all jobs restart from scratch.

It returns the id of the *new* workflow the rerun created, which is what the caller needs to follow the run they just started — the id passed in belongs to the old workflow and is of no further use.

The request field is "is_from_failed". Not "from_failed": that is the name the v2 endpoint and the service's own internal client use, and the v3 handler tolerates unknown fields rather than rejecting them — so sending the v2 name here silently reran everything from scratch, with a 201 and a new workflow to make it look like it had worked.

func (*Client) ResolveOrgID 

func (c *Client) ResolveOrgID(ctx context.Context, slug string) (uuid.UUID, error)

ResolveOrgID resolves an organization slug (e.g. "gh/acme") to its UUID via GET /api/v3/orgs?filter[slug]=<slug>.

The endpoint is a collection: a slug matching no org returns an empty list (not a 404), which is surfaced as ErrOrgNotFound.

func (*Client) ResourceClassByName added in v1.0.47226 

func (c *Client) ResourceClassByName(ctx context.Context, resourceClass string) (*ResourceClass, error)

ResourceClassByName returns the resource class with the given fully qualified namespace/name resource class.

func (*Client) RollbackProject added in v1.0.48275 

func (c *Client) RollbackProject(ctx context.Context, projectID string, req V3RollbackRequest) (*V3Rollback, error)

RollbackProject rolls a deployed component of the given project back to an earlier version.

func (*Client) SearchRunsV3 

func (c *Client) SearchRunsV3(ctx context.Context, params RunSearchParams) ([]RunV3, error)

SearchRunsV3 searches for runs using the V3 search endpoint. It paginates transparently when params.Limit exceeds maxRunsPageSize.

func (*Client) SetContextEnvVar 

func (c *Client) SetContextEnvVar(ctx context.Context, contextID uuid.UUID, name, value string) error

SetContextEnvVar adds or updates an environment variable in a context.

func (*Client) SetEnvVar 

func (c *Client) SetEnvVar(ctx context.Context, projectSlug, name, value string) (*EnvVar, error)

SetEnvVar creates or updates a project environment variable.

func (*Client) SetOrbListed 

func (c *Client) SetOrbListed(ctx context.Context, orbID string, listed bool) error

SetOrbListed sets the listed status of an orb package.

func (*Client) SetPolicySettings 

func (c *Client) SetPolicySettings(ctx context.Context, ownerID, policyCtx string, settings DecisionSettings) (DecisionSettings, error)

SetPolicySettings enables or disables policy enforcement.

func (*Client) SetupProviderConnection added in v1.0.48571 

func (c *Client) SetupProviderConnection(ctx context.Context, orgID, provider, returnURL string) (*ProviderConnectionSetup, error)

SetupProviderConnection starts connecting a provider to an organization. orgID must be the organization UUID; returnURL is where the provider sends the user once the flow completes.

Every call mints a fresh, hour-long state token, so this is not idempotent: call it when a user is about to be sent to the provider, not to probe.

func (*Client) StreamJobTests 

func (c *Client) StreamJobTests(ctx context.Context, jobID uuid.UUID, fn func(TestResult)) error

StreamJobTests fetches the test metadata for a job identified by UUID, invoking fn for each TestResult as it is decoded from the JSONL response. The endpoint returns JSONL (one TestResult per line) rather than a JSON array, so records are handed to fn as they arrive rather than buffered. The returned error reports transport or decode failures, not anything fn does.

func (*Client) TriggerPipeline 

func (c *Client) TriggerPipeline(ctx context.Context, projectSlug, branch string, params map[string]any) (*TriggerResponse, error)

TriggerPipeline triggers a new pipeline for the given project and branch. params may be nil or empty if no pipeline parameters are needed.

func (*Client) TriggerPipelineRun 

func (c *Client) TriggerPipelineRun(ctx context.Context, projectSlug string, input TriggerPipelineRunInput) (*TriggerPipelineRunResult, error)

TriggerPipelineRun triggers a pipeline run via the recommended v2 endpoint. projectSlug must be in "vcs/org/repo" form (e.g. "gh/myorg/myrepo").

func (*Client) UpdateIOSSigningConfigProfile added in v1.0.47993 

func (c *Client) UpdateIOSSigningConfigProfile(ctx context.Context, configID uuid.UUID, fileName, blob string) error

UpdateIOSSigningConfigProfile adds or replaces a provisioning profile on an existing signing config, without recreating it. The server matches profiles by the bundle identifier and profile type embedded in the provisioning profile file itself, a profile with the same bundle ID and type as an existing one replaces it in place; any other pairing is added as a new profile. blob must be base64-encoded. The server returns 204 No Content on success.

func (*Client) UpdateOrgSettings 

func (c *Client) UpdateOrgSettings(ctx context.Context, orgID uuid.UUID, update OrgSettingsUpdate) (*OrgSettingsAttributes, error)

UpdateOrgSettings updates org settings via POST /api/v3/orgs/:id/update-settings. Only the fields set in update are changed; omitted fields are left as-is.

func (*Client) UpdateProjectSettings 

func (c *Client) UpdateProjectSettings(ctx context.Context, projectID uuid.UUID, update ProjectSettingsUpdate) (*ProjectSettingsAttributes, error)

UpdateProjectSettings updates project settings via POST /api/v3/projects/:id/update-settings. Only the fields set in update are changed; omitted fields are left as-is.

func (*Client) UpdateResourceClass added in v1.0.51242 

func (c *Client) UpdateResourceClass(ctx context.Context, id uuid.UUID, description string) (*ResourceClass, error)

UpdateResourceClass updates the description of a runner resource class. The request body is flat ({description: ...}), not the data envelope other v3 writes use, but the response is the usual v3 data entity.

func (*Client) UploadIOSCertificate 

func (c *Client) UploadIOSCertificate(ctx context.Context, orgID uuid.UUID, fileName, blob, password string) (uuid.UUID, error)

UploadIOSCertificate uploads a .p12 certificate to the org's secure storage. blob must be base64-encoded. Returns the new certificate ID.

func (*Client) ValidateOrbYAML 

func (c *Client) ValidateOrbYAML(ctx context.Context, yaml, orgID string) (*OrbValidation, error)

ValidateOrbYAML validates orb YAML. orgID is optional.

type Collaboration 

type Collaboration struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Slug    string `json:"slug"` // e.g. "gh/myorg"
	VCSType string `json:"vcs_type"`
}

Collaboration represents an organization the authenticated user belongs to.

type CompileInput added in v1.0.47692 

type CompileInput struct {
	// ConfigYAML is the raw pipeline config to compile. Required.
	ConfigYAML string
	// OrgID is the owning organization UUID. Optional; supplying one enables
	// private and namespaced orb resolution.
	OrgID string
	// PreviewNext enables "config next", previewing upcoming and potentially
	// breaking config changes.
	PreviewNext bool
	// PipelineValues is the << pipeline.* >> template context. The CLI
	// fabricates it locally from git state (see configcmd.LocalPipelineValues).
	PipelineValues map[string]any
	// PipelineParameters are the user parameters injected at
	// << pipeline.parameters.* >>.
	PipelineParameters map[string]any
}

CompileInput holds everything a config compilation needs. It is the input to Compile, in the CLI's own terms rather than the wire shape.

type CompileResult added in v1.0.47692 

type CompileResult struct {
	Valid        bool
	CompiledYAML string
	Errors       []string
}

CompileResult is the outcome of a config compilation. An invalid config is not an error: Valid is false and Errors holds the compilation messages.

type Config 

type Config struct {
	BaseURL string
	Token   string
	Version string
	Agent   string

	Transport http.RoundTripper
	// OnWarn, when non-nil, is called with a plain-text deprecation warning.
	// See httpcl.Config.OnWarn for details.
	OnWarn func(msg string)
}

type Context 

type Context struct {
	ID        uuid.UUID
	Name      string
	CreatedAt time.Time
	OrgID     uuid.UUID
}

Context is a CircleCI context — a named collection of secret environment variables shared across pipelines in an organization.

OrgID is populated by GetContext but not by ListContexts: the list response carries no references, since every item in it belongs to the org that was filtered on.

type ContextDetail 

type ContextDetail struct {
	ID                   uuid.UUID
	Name                 string
	CreatedAt            time.Time
	OrgID                uuid.UUID
	EnvironmentVariables []ContextEnvVar
	Restrictions         []ContextRestriction
}

ContextDetail is a context together with everything the CLI shows for it.

v2 served all of this from one endpoint; v3 splits it three ways — the context, its environment variables and its restrictions. GetContextDetail reassembles it.

type ContextEnvVar 

type ContextEnvVar struct {
	Variable       string
	TruncatedValue string
	CreatedAt      time.Time
	UpdatedAt      time.Time
	ContextID      uuid.UUID
}

ContextEnvVar is an environment variable stored in a context. The value is never returned by the API; TruncatedValue is the last few characters, enough to identify which secret is in a slot.

type ContextRestriction 

type ContextRestriction struct {
	ContextID       uuid.UUID
	ID              uuid.UUID
	Name            string
	RestrictionType string
	MatchPattern    string
}

ContextRestriction is a restriction limiting which projects, groups or pipelines may use a context.

Name is the resolved name of whatever the restriction points at — a project's or a group's. It is empty for expression restrictions, which have nothing to name, and for a subject the API could not resolve.

type CreateNamespaceRequest 

type CreateNamespaceRequest struct {
	Name  string `json:"name"`
	OrgID string `json:"org_id"`
}

type CreateOrbPackageRequest 

type CreateOrbPackageRequest struct {
	Name        string `json:"name"`
	NamespaceID string `json:"namespace_id"`
	IsPrivate   bool   `json:"is_private"`
}

CreateOrbPackageRequest is the body for creating an orb.

type CreatePipelineDefinitionInput 

type CreatePipelineDefinitionInput struct {
	Name                 string
	Description          string
	ConfigProvider       string
	ConfigRepoID         string
	ConfigRepoFullName   string
	ConfigFilePath       string
	ConfigFileType       string
	CheckoutProvider     string
	CheckoutRepoID       string
	CheckoutRepoFullName string
}

CreatePipelineDefinitionInput contains all fields for creating a pipeline definition. The RepoFullName fields are required by providers that address a repository by owner and name rather than by id, and ignored by the rest. ConfigFileType is optional; pass "github-actions" for a GitHub Actions workflow file.

type CreateTriggerInput added in v1.0.48254 

type CreateTriggerInput struct {
	ProjectID            string
	PipelineDefinitionID string
	Provider             string
	RepoID               string
	RepoFullName         string
	EventPreset          string
	ConfigRef            string
	CheckoutRef          string
}

CreateTriggerInput contains the fields for creating a trigger. Provider must be one of: github_app, github_server, github_oauth, origin, webhook, schedule. RepoID is the repository external ID, required by every VCS-backed provider; RepoFullName is additionally required by providers that address a repository by owner and name rather than by id.

type DecisionLogsRequest 

type DecisionLogsRequest struct {
	Status    string
	After     *time.Time
	Before    *time.Time
	Branch    string
	ProjectID string
	Offset    int
}

DecisionLogsRequest holds optional filters for GetDecisionLogs.

type DecisionSettings 

type DecisionSettings struct {
	Enabled bool `json:"enabled"`
}

DecisionSettings controls whether policy decisions are enforced for an owner.

type EnvVar 

type EnvVar struct {
	Name      string     `json:"name"`
	Value     string     `json:"value"`
	CreatedAt *time.Time `json:"created_at"`
}

EnvVar is a project environment variable. The value is masked in list responses; it is only returned on set.

type Error 

type Error struct {
	ID     string      `json:"id"`
	Title  string      `json:"title"`
	Detail string      `json:"detail"`
	Source ErrorSource `json:"source"`
}

Error is the common error envelope returned by v3 API endpoints: 

{"error": {"id": "...", "title": "...", "detail": "...", "source": {...}}}

func ParseError 

func ParseError(err error) (*Error, bool)

ParseError extracts the v3 error envelope from the response body of an *httpcl.HTTPError. It returns false when err is not an HTTP error or the body does not carry the envelope (e.g. v1/v2 endpoints, HTML error pages).

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Message 

func (e *Error) Message() string

Message renders the error for human display: "title: detail" on the first line, followed by the source location and error id when present.

type ErrorSource 

type ErrorSource struct {
	Error   string `json:"error"`
	Offset  int    `json:"offset"`
	Pointer string `json:"pointer"`
}

ErrorSource locates the cause of an Error within the request, e.g. a JSON pointer to an invalid field.

type Function added in v1.0.51515 

type Function struct {
	ID            uuid.UUID
	Name          string
	Description   string
	LatestVersion string
	Versions      []FunctionVersion
}

Function is a published CircleCI function. Name is the VCS-style identifier it is published under, e.g. "github.com/circleci-functions/setup-go".

func (*Function) Find added in v1.0.52018 

func (f *Function) Find(version string) (FunctionVersion, bool)

Find returns the named version, or false when it is not published.

type FunctionDescriptor added in v1.0.52018 

type FunctionDescriptor struct {
	Version string
	Content map[string]any
}

FunctionDescriptor is a version's published descriptor. Content is untyped because a descriptor is served exactly as published and its shape can differ between versions of the same function.

type FunctionVersion added in v1.0.51515 

type FunctionVersion struct {
	ID      uuid.UUID
	Version string
}

FunctionVersion is one published version of a function.

type IOSCertificate 

type IOSCertificate struct {
	ID       uuid.UUID `json:"id,omitempty"`
	FileName string    `json:"file_name,omitempty"`
	CertType string    `json:"cert_type,omitempty"`
}

IOSCertificate is an Apple .p12 code signing certificate stored in CircleCI's secure storage.

type IOSCertificateRef 

type IOSCertificateRef struct {
	FileName string `json:"file_name,omitempty"`
	CertType string `json:"cert_type,omitempty"`
}

IOSCertificateRef is the embedded certificate descriptor returned by the signing-config list endpoint. Holds only display fields.

type IOSProvisioningProfile 

type IOSProvisioningProfile struct {
	ID       string `json:"id,omitempty"`
	FileName string `json:"file_name"`
	Blob     string `json:"blob,omitempty"`
}

IOSProvisioningProfile is a base64-encoded Apple provisioning profile. Blob is populated on create; list responses only echo the file name and ID

type IOSSigningConfig 

type IOSSigningConfig struct {
	ID                   uuid.UUID                `json:"id,omitempty"`
	Name                 string                   `json:"name,omitempty"`
	Certificate          *IOSCertificateRef       `json:"certificate,omitempty"`
	ProvisioningProfiles []IOSProvisioningProfile `json:"provisioning_profiles,omitempty"`
}

IOSSigningConfig is an iOS signing config: a named pairing of a certificate and one or more provisioning profiles, referenced by name in pipeline config.

type Job 

type Job struct {
	Number    int64      `json:"job_number"`
	Name      string     `json:"name"`
	Status    string     `json:"status"`
	StartedAt time.Time  `json:"started_at"`
	StoppedAt *time.Time `json:"stopped_at"`
	Steps     []JobStep  `json:"steps"`
}

Job holds the details of a CircleCI job including its steps.

type JobResourceClass added in v1.0.48122 

type JobResourceClass struct {
	Name string `json:"name"`
	// CPUCount is how many cores the resource class provides, so a CPUCores
	// sample equal to it means the job was saturating the executor.
	CPUCount float64 `json:"cpu_count"`
	// MemoryLimitBytes is the executor's memory ceiling.
	MemoryLimitBytes int64 `json:"memory_limit_bytes"`
}

JobResourceClass is the executor a job ran on, and the limits its usage should be read against.

type JobResourceUsage added in v1.0.48122 

type JobResourceUsage struct {
	ID            uuid.UUID                   `json:"id"`
	ResourceClass JobResourceClass            `json:"resource_class"`
	Executions    []JobResourceUsageExecution `json:"executions"`
}

JobResourceUsage is a job's sampled CPU and memory usage, one series per parallel execution.

type JobResourceUsageExecution added in v1.0.48122 

type JobResourceUsageExecution struct {
	Index          int       `json:"execution"`
	IntervalMS     int       `json:"interval_ms"`
	CPUCores       []float64 `json:"cpu_cores"`
	MemoryBytes    []int64   `json:"memory_bytes"`
	NetworkRxBytes int64     `json:"network_rx_bytes"`
	NetworkTxBytes int64     `json:"network_tx_bytes"`
}

JobResourceUsageExecution is one parallel execution's usage series. CPUCores and MemoryBytes are sampled every IntervalMS milliseconds from the start of the execution, so index i is the sample at i*IntervalMS elapsed; both are empty for an execution too short to have been sampled at all.

The network counters are cumulative totals for the whole execution rather than series, which is why they are scalars here.

func (JobResourceUsageExecution) Duration added in v1.0.48122 

func (e JobResourceUsageExecution) Duration() time.Duration

Duration is the time span the samples cover: one interval per sample, so a single sample covers one interval rather than none.

func (JobResourceUsageExecution) Interval added in v1.0.48122 

func (e JobResourceUsageExecution) Interval() time.Duration

Interval is the sampling period as a duration. It is zero when the API reported no interval, which callers should read as "sample spacing unknown" and not as "no time passed".

func (JobResourceUsageExecution) Samples added in v1.0.48122 

func (e JobResourceUsageExecution) Samples() int

Samples is how many samples the execution recorded. The CPU and memory series are sampled together, so the shorter of the two bounds what can be plotted side by side.

type JobStep 

type JobStep struct {
	Name    string       `json:"name"`
	Actions []StepAction `json:"actions"`
}

JobStep is a named step within a job.

type JobV3 

type JobV3 struct {
	ID         uuid.UUID        `json:"id"`
	Name       string           `json:"name"`
	Type       string           `json:"type"`
	Phase      string           `json:"phase"`
	Outcome    string           `json:"outcome,omitempty"`
	StartedAt  time.Time        `json:"started_at"`
	StoppedAt  *time.Time       `json:"stopped_at,omitempty"`
	Executions []JobV3Execution `json:"executions"`
	ProjectID  uuid.UUID        `json:"project_id"`
	PipelineID uuid.UUID        `json:"pipeline_id"`
	WorkflowID uuid.UUID        `json:"workflow_id"`
}

JobV3 holds job detail from the V3 API.

func (JobV3) Status 

func (j JobV3) Status() string

Status derives a display status from phase and outcome.

type JobV3Execution 

type JobV3Execution struct {
	Index int         `json:"index"`
	Steps []JobV3Step `json:"steps"`
}

JobV3Execution groups the steps that ran on a single executor.

type JobV3Step 

type JobV3Step struct {
	Name      string     `json:"name"`
	Type      string     `json:"type"`
	Num       int        `json:"num"`
	Phase     string     `json:"phase"`
	Outcome   string     `json:"outcome,omitempty"`
	ExitCode  *int       `json:"exit_code,omitempty"`
	Command   string     `json:"command,omitempty"`
	StartedAt time.Time  `json:"started_at"`
	StoppedAt *time.Time `json:"stopped_at,omitempty"`
}

JobV3Step is a single step within a V3 job response.

func (JobV3Step) Status 

func (s JobV3Step) Status() string

Status derives a display status from phase and outcome.

type LogLine 

type LogLine struct {
	Type    string `json:"type"` // "out" or "err"
	Time    string `json:"time"`
	Message string `json:"message"`
}

LogLine is a single line of output from a step action.

type Me 

type Me struct {
	Name      string    `json:"name"`
	Login     string    `json:"login"`
	ID        uuid.UUID `json:"id"`
	AvatarURL string    `json:"avatar_url"`
}

type MyRunsParams 

type MyRunsParams struct {
	// Limit caps the page size; a value <= 0 uses the server default.
	Limit int
	// Status narrows the list to runs with that pipeline status (e.g. "failed",
	// "on_hold"); an empty status lists every status.
	Status string
	// From and To bound the list to runs created within that window
	// (filter[from]/filter[to], RFC3339). A nil bound is omitted, letting the
	// endpoint apply its own default for that side.
	From *time.Time
	To   *time.Time
}

MyRunsParams configures a ListMyRunsV3 request. All fields are optional: the zero value lists every recent run the endpoint defaults to.

type Namespace 

type Namespace struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

Namespace represents a CircleCI orb registry namespace.

type OrbCategory 

type OrbCategory struct {
	ID   string
	Name string
}

OrbCategory is a domain-level orb category.

type OrbPackage 

type OrbPackage struct {
	ID                     string
	Name                   string
	Namespace              string
	NamespaceID            string
	IsPrivate              bool
	IsListed               bool
	CreatedAt              string
	LatestVersion          string
	LatestVersionAt        string
	Last30DaysBuildCount   int64
	Last30DaysProjectCount int64
	Last30DaysOrgCount     int64
	Categories             []OrbCategory
}

OrbPackage is a domain-level orb package.

type OrbValidation 

type OrbValidation struct {
	Valid      bool
	OutputYAML string
	Errors     []string
}

OrbValidation holds the result of a validate or process API call.

type OrbVersion 

type OrbVersion struct {
	ID        string
	OrbID     string
	OrbName   string
	Version   string
	CreatedAt string
}

OrbVersion is a domain-level orb version.

type OrgInfo 

type OrgInfo struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Slug    string `json:"slug"`
	VCSType string `json:"vcs_type"`
}

OrgInfo is returned by POST /api/v2/organization.

type OrgSettingsAttributes 

type OrgSettingsAttributes struct {
	RunnerTOSAccepted               bool `json:"is_runner_terms_of_service_accepted"`
	AIErrorSummarization            bool `json:"enable_ai_error_summarization"`
	AIAgents                        bool `json:"enable_ai_agents"`
	UnversionedConfig               bool `json:"enable_unversioned_config"`
	CertifiedPublicOrbs             bool `json:"enable_certified_public_orbs"`
	ChunkIPRanges                   bool `json:"enable_chunk_ip_ranges"`
	MarketingTracking               bool `json:"enable_marketing_tracking"`
	MinorAIFeatures                 bool `json:"enable_minor_ai_features"`
	PreferencesTracking             bool `json:"enable_preferences_tracking"`
	PrivateOrbs                     bool `json:"enable_private_orbs"`
	StatisticsTracking              bool `json:"enable_statistics_tracking"`
	UncertifiedPublicOrbs           bool `json:"enable_uncertified_public_orbs"`
	UserCheckoutKeysDisabled        bool `json:"is_user_checkout_keys_disabled"`
	DisableRunning                  bool `json:"is_running_disabled"`
	PrivacyOptoutEnforced           bool `json:"is_privacy_optout_enforced"`
	ImageBrownouts                  bool `json:"enable_image_brownouts"`
	ContextGroupRestrictionRequired bool `json:"is_context_group_restriction_required"`
	ResourceClassBrownouts          bool `json:"enable_resource_class_brownouts"`
}

OrgSettingsAttributes is the "attributes" object returned by GET /api/v3/orgs/:id/settings and POST /api/v3/orgs/:id/update-settings. Field order follows the order the attributes are documented in.

type OrgSettingsUpdate 

type OrgSettingsUpdate struct {
	RunnerTOSAccepted               *bool `json:"is_runner_terms_of_service_accepted,omitempty"`
	AIErrorSummarization            *bool `json:"enable_ai_error_summarization,omitempty"`
	AIAgents                        *bool `json:"enable_ai_agents,omitempty"`
	UnversionedConfig               *bool `json:"enable_unversioned_config,omitempty"`
	CertifiedPublicOrbs             *bool `json:"enable_certified_public_orbs,omitempty"`
	ChunkIPRanges                   *bool `json:"enable_chunk_ip_ranges,omitempty"`
	MarketingTracking               *bool `json:"enable_marketing_tracking,omitempty"`
	MinorAIFeatures                 *bool `json:"enable_minor_ai_features,omitempty"`
	PreferencesTracking             *bool `json:"enable_preferences_tracking,omitempty"`
	PrivateOrbs                     *bool `json:"enable_private_orbs,omitempty"`
	StatisticsTracking              *bool `json:"enable_statistics_tracking,omitempty"`
	UncertifiedPublicOrbs           *bool `json:"enable_uncertified_public_orbs,omitempty"`
	UserCheckoutKeysDisabled        *bool `json:"is_user_checkout_keys_disabled,omitempty"`
	DisableRunning                  *bool `json:"is_running_disabled,omitempty"`
	PrivacyOptoutEnforced           *bool `json:"is_privacy_optout_enforced,omitempty"`
	ImageBrownouts                  *bool `json:"enable_image_brownouts,omitempty"`
	ContextGroupRestrictionRequired *bool `json:"is_context_group_restriction_required,omitempty"`
	ResourceClassBrownouts          *bool `json:"enable_resource_class_brownouts,omitempty"`
}

OrgSettingsUpdate is the body for POST /api/v3/orgs/:id/update-settings. Only non-nil fields are sent; omitting a field leaves that setting unchanged.

type Organization added in v1.0.50034 

type Organization struct {
	ID   uuid.UUID
	Name string
	// VCS is the version control provider backing the org ("github",
	// "bitbucket"). Empty for a standalone CircleCI org, which has no provider.
	VCS string
}

Organization is an organization the authenticated user belongs to, as returned by GET /api/v3/orgs.

The collection carries no slug — see ListOrgs.

type Pipeline 

type Pipeline struct {
	ID                uuid.UUID                  `json:"id"`
	State             string                     `json:"state"`
	Number            int64                      `json:"number"`
	CreatedAt         time.Time                  `json:"created_at"`
	UpdatedAt         time.Time                  `json:"updated_at"`
	ProjectSlug       string                     `json:"project_slug"`
	Trigger           PipelineTrigger            `json:"trigger"`
	TriggerParameters *PipelineTriggerParameters `json:"trigger_parameters,omitempty"`
	VCS               *PipelineVCS               `json:"vcs,omitempty"`
	Errors            []PipelineError            `json:"errors,omitempty"`
}

Pipeline represents a CircleCI pipeline.

type PipelineDefinition 

type PipelineDefinition struct {
	ID             string                    `json:"id"`
	Name           string                    `json:"name"`
	Description    string                    `json:"description,omitempty"`
	CreatedAt      time.Time                 `json:"created_at"`
	ConfigSource   *PipelineDefinitionSource `json:"config_source,omitempty"`
	CheckoutSource *PipelineDefinitionSource `json:"checkout_source,omitempty"`
}

PipelineDefinition represents a CircleCI pipeline definition.

type PipelineDefinitionRepo 

type PipelineDefinitionRepo struct {
	FullName   string `json:"full_name,omitempty"`
	ExternalID string `json:"external_id,omitempty"`
}

PipelineDefinitionRepo holds repository info for a pipeline definition source.

type PipelineDefinitionSource 

type PipelineDefinitionSource struct {
	Provider string                  `json:"provider,omitempty"`
	Repo     *PipelineDefinitionRepo `json:"repo,omitempty"`
	FilePath string                  `json:"file_path,omitempty"`
}

PipelineDefinitionSource describes a config or checkout source.

type PipelineError 

type PipelineError struct {
	Type    string `json:"type"`
	Message string `json:"message"`
}

PipelineError is an error associated with a pipeline.

type PipelineTrigger 

type PipelineTrigger struct {
	Type       string    `json:"type"`
	ReceivedAt time.Time `json:"received_at"`
	Actor      Actor     `json:"actor"`
}

PipelineTrigger describes what triggered a pipeline.

type PipelineTriggerGit 

type PipelineTriggerGit struct {
	Branch      string `json:"branch"`
	CheckoutSHA string `json:"checkout_sha"`
}

PipelineTriggerGit holds the git fields within trigger_parameters.

type PipelineTriggerParameters 

type PipelineTriggerParameters struct {
	Git *PipelineTriggerGit `json:"git,omitempty"`
}

PipelineTriggerParameters holds git context for pipeline-definition-triggered runs. It is absent on legacy VCS-triggered pipelines (which use the vcs field instead).

type PipelineVCS 

type PipelineVCS struct {
	ProviderName        string     `json:"provider_name"`
	OriginRepositoryURL string     `json:"origin_repository_url"`
	TargetRepositoryURL string     `json:"target_repository_url"`
	Revision            string     `json:"revision"`
	Branch              string     `json:"branch,omitempty"`
	Tag                 string     `json:"tag,omitempty"`
	Commit              *VCSCommit `json:"commit,omitempty"`
}

PipelineVCS holds version-control metadata for a pipeline.

type PolicyBundle 

type PolicyBundle map[string]string

PolicyBundle is a map of policy name to Rego source content.

type ProjectFilter added in v1.0.50047 

type ProjectFilter struct {
	Following bool
	OrgID     string
	Name      string
	Slug      string
}

ProjectFilter scopes GET /api/v3/projects. The endpoint requires at least one of Following, OrgID or Slug, and rejects Slug combined with any other filter, so callers must not set both. Name narrows Following or OrgID by name.

type ProjectInfo 

type ProjectInfo struct {
	ID               string   `json:"id"`
	Slug             string   `json:"slug"`
	Name             string   `json:"name"`
	OrganizationName string   `json:"organization_name"`
	OrganizationSlug string   `json:"organization_slug"`
	OrganizationID   string   `json:"organization_id"`
	VCSInfo          *VCSInfo `json:"vcs_info"`
}

ProjectInfo contains detailed information about a CircleCI project.

type ProjectRef 

type ProjectRef struct {
	ID    uuid.UUID
	Name  string
	OrgID uuid.UUID
}

ProjectRef is a project resolved from its slug, carrying the UUIDs that the v3 API needs. Returned by GetProjectBySlug.

type ProjectSettingsAttributes 

type ProjectSettingsAttributes struct {
	AIErrorSummarization      bool     `json:"enable_ai_error_summarization"`
	AutoCancelBuilds          bool     `json:"enable_auto_cancel_redundant_workflows"`
	BuildForkPRs              bool     `json:"enable_building_fork_prs"`
	BuildPRsOnly              bool     `json:"is_build_prs_only"`
	CanPassSecretsToForkPR    bool     `json:"can_pass_secrets_to_fork_pr_jobs"`
	CanSetGitHubStatus        bool     `json:"can_set_github_status"`
	DisableRunning            bool     `json:"is_running_disabled"`
	DisableSSH                bool     `json:"is_ssh_disabled"`
	DynamicConfig             bool     `json:"enable_dynamic_config"`
	IsAdminRequiredForWriting bool     `json:"is_admin_required_for_writing_settings"`
	IsOSS                     bool     `json:"is_oss"`
	PROnlyBranchOverrides     []string `json:"pr_only_branch_overrides"`
	UnversionedConfig         bool     `json:"enable_unversioned_config"`
}

ProjectSettingsAttributes is the "attributes" object returned by GET /api/v3/projects/:id/settings and POST /api/v3/projects/:id/update-settings.

type ProjectSettingsUpdate 

type ProjectSettingsUpdate struct {
	AIErrorSummarization      *bool     `json:"enable_ai_error_summarization,omitempty"`
	AutoCancelBuilds          *bool     `json:"enable_auto_cancel_redundant_workflows,omitempty"`
	BuildForkPRs              *bool     `json:"enable_building_fork_prs,omitempty"`
	BuildPRsOnly              *bool     `json:"is_build_prs_only,omitempty"`
	CanPassSecretsToForkPR    *bool     `json:"can_pass_secrets_to_fork_pr_jobs,omitempty"`
	CanSetGitHubStatus        *bool     `json:"can_set_github_status,omitempty"`
	DisableRunning            *bool     `json:"is_running_disabled,omitempty"`
	DisableSSH                *bool     `json:"is_ssh_disabled,omitempty"`
	DynamicConfig             *bool     `json:"enable_dynamic_config,omitempty"`
	IsAdminRequiredForWriting *bool     `json:"is_admin_required_for_writing_settings,omitempty"`
	IsOSS                     *bool     `json:"is_oss,omitempty"`
	PROnlyBranchOverrides     *[]string `json:"pr_only_branch_overrides,omitempty"`
	UnversionedConfig         *bool     `json:"enable_unversioned_config,omitempty"`
}

ProjectSettingsUpdate is the body for POST /api/v3/projects/:id/update-settings. Only non-nil fields are sent; omitting a field leaves that setting unchanged.

type ProjectSummary added in v1.0.50047 

type ProjectSummary struct {
	ID      uuid.UUID
	Name    string
	OrgID   uuid.UUID
	OrgName string
}

ProjectSummary is a project as the v3 collection reports it: its UUID and name, plus the owning org denormalised into references.org.

type ProviderConnection added in v1.0.48454 

type ProviderConnection struct {
	// ID is the connection's CircleCI UUID.
	ID string
	// Provider is the integration, e.g. "github_app".
	Provider string
	// ExternalID is the provider's own id for the installation.
	ExternalID string
	// Login is the provider account the connection is installed on.
	Login string
	// RepositorySelection is "all" or "selected" when present.
	RepositorySelection string
	// AuthorizedUsername is the calling user's account with the provider.
	AuthorizedUsername string
	// ConnectionError describes why the provider could not be reached, if it
	// could not be.
	ConnectionError string
}

ProviderConnection is an organization's connection to a VCS provider, as returned by GET /api/v3/provider/connections.

The presence of a connection is what says the provider is connected. The enrichment fields come from a live call out to the provider, so they are absent when ConnectionError is set — a connection that reports an error is still a connection.

type ProviderConnectionSetup added in v1.0.48571 

type ProviderConnectionSetup struct {
	// NextStep is what has to happen next, one of the ConnectionNextStep values.
	NextStep string
	// URL is where to send the user. Present when NextStep is redirect.
	URL string
	// StateToken ties the provider's callback back to this setup. Present when
	// NextStep is register.
	StateToken string
}

ProviderConnectionSetup is where to send a user to finish connecting a provider, as returned by POST /api/v3/provider/connections/setup. Nothing is connected when it is returned: the connection only exists once the user completes the flow at the provider.

type ProviderRepository added in v1.0.48658 

type ProviderRepository struct {
	// ID is the provider's own repository id — the external ID used as the repo
	// reference in pipeline definitions and triggers. It is a string because it is
	// numeric for some providers and text for others.
	ID string
	// FullName is the "owner/repo" name.
	FullName string
	// Name is the repository name without its owner.
	Name string
	// Owner is the account the repository belongs to.
	Owner string
	// DefaultBranch is the repository's default branch.
	DefaultBranch string
	// IsPrivate reports whether the repository is private. Providers that do not
	// report visibility are reported private, which is the conservative reading.
	IsPrivate bool
	// Provider is the integration the repository was listed through.
	Provider string
}

ProviderRepository is a repository an organization's provider connection can reach, as returned by GET /api/v3/provider/repositories.

What "can reach" means depends on the provider. Where access is granted per user, two members of one organization can see different lists; where it is granted per installation, every member who can view the org sees all of it.

type PublishOrbVersionRequest 

type PublishOrbVersionRequest struct {
	OrbID   string `json:"orb_id"`
	YAML    string `json:"yaml"`
	Version string `json:"version"`
}

PublishOrbVersionRequest is the body for publishing an orb version.

type Release added in v1.0.47519 

type Release struct {
	Tool        string    // GitHub repo name the release belongs to, e.g. "circleci-cli"
	Version     string    // semver, no leading "v" (the server strips it)
	PublishedAt time.Time // release publication time, UTC
}

Release is the latest released version of a CircleCI tool.

type RenameNamespaceRequest 

type RenameNamespaceRequest struct {
	Name    string `json:"-"`    // current name, resolved to an ID
	NewName string `json:"name"` // new name, sent in request body
}

type ResourceClass 

type ResourceClass struct {
	ID            string `json:"id"`
	ResourceClass string `json:"resource_class"`
	Description   string `json:"description"`
}

ResourceClass is a CircleCI runner resource class.

type RunCommit 

type RunCommit struct {
	Subject     string `json:"subject,omitempty"`
	URL         string `json:"url,omitempty"`
	AuthorName  string `json:"author_name,omitempty"`
	AuthorLogin string `json:"author_login,omitempty"`
}

RunCommit holds the commit metadata attached to a run event.

type RunError 

type RunError struct {
	Type    string `json:"type"`
	Message string `json:"message"`
}

RunError holds a config or setup error from the V3 API.

type RunSearchParams 

type RunSearchParams struct {
	ProjectIDs []string
	From       time.Time
	To         time.Time
	Filter     string
	OrderBy    string
	Limit      int
	Cursor     string
}

RunSearchParams configures a V3 runs search request.

type RunV3 

type RunV3 struct {
	ID             uuid.UUID    `json:"id"`
	Phase          string       `json:"phase"`
	Outcome        string       `json:"outcome,omitempty"`
	CurrentOutcome string       `json:"current_outcome,omitempty"`
	Branch         string       `json:"branch,omitempty"`
	Tag            string       `json:"tag,omitempty"`
	Revision       string       `json:"revision,omitempty"`
	RepositoryURL  string       `json:"repository_url,omitempty"`
	Commit         *RunCommit   `json:"commit,omitempty"`
	CreatedAt      time.Time    `json:"created_at"`
	ProjectID      uuid.UUID    `json:"project_id"`
	Errors         []RunError   `json:"errors,omitempty"`
	Warnings       []RunWarning `json:"warnings,omitempty"`
}

RunV3 holds run detail from the V3 API.

func (RunV3) Status 

func (r RunV3) Status() string

Status derives a display status from phase and outcome.

type RunWarning added in v1.2.0 

type RunWarning struct {
	Type        string `json:"type"`
	Message     string `json:"message"`
	Description string `json:"description,omitempty"`
	URL         string `json:"url,omitempty"`
}

RunWarning holds a non-fatal warning from the V3 API.

type RunnerAgent added in v1.0.51336 

type RunnerAgent struct {
	ID         uuid.UUID `json:"id"`
	Attributes struct {
		Name             string    `json:"name"`
		IsBusy           bool      `json:"is_busy"`
		Version          string    `json:"version"`
		FirstConnectedAt time.Time `json:"first_connected_at"`
		LastConnectedAt  time.Time `json:"last_connected_at"`
	} `json:"attributes"`
	References struct {
		ResourceClass struct {
			ID         uuid.UUID `json:"id"`
			Attributes struct {
				ResourceClass string `json:"resource_class"`
			} `json:"attributes"`
		} `json:"resource_class"`
	} `json:"references"`
}

RunnerAgent is a connected runner agent returned by GET /api/v3/runner/agents.

type RunnerToken 

type RunnerToken struct {
	ID              string `json:"id"`
	ResourceClass   string `json:"resource_class"`
	ResourceClassID string `json:"resource_class_id"`
	Nickname        string `json:"nickname"`
	CreatedAt       string `json:"created_at"`
	// Token is only populated on creation.
	Token string `json:"token,omitempty"`
}

RunnerToken is an authentication token for a resource class.

type StepAction 

type StepAction struct {
	Index     int        `json:"index"`
	Step      int        `json:"step"`
	Name      string     `json:"name"`
	Status    string     `json:"status"`
	ExitCode  *int       `json:"exit_code"`
	StartedAt time.Time  `json:"start_time"`
	StoppedAt *time.Time `json:"end_time"`
}

StepAction is a single action within a step, carrying the output URL.

type TestResult 

type TestResult struct {
	Classname string  `json:"classname"` // suite/package the test belongs to
	Name      string  `json:"name"`      // test name
	Result    string  `json:"result"`    // "success", "failure", "skipped", ...
	RunTime   float64 `json:"run_time"`  // seconds
	Message   string  `json:"message"`   // failure/skip detail, empty on success
}

TestResult is a single test's outcome as reported by a job's test metadata. The /api/v3/jobs/{id}/tests endpoint streams these as newline-delimited JSON (JSONL), one record per line.

type Trigger 

type Trigger struct {
	ID          string             `json:"id"`
	CreatedAt   time.Time          `json:"created_at"`
	EventName   string             `json:"event_name,omitempty"`
	EventSource TriggerEventSource `json:"event_source"`
	EventPreset string             `json:"event_preset,omitempty"`
	ConfigRef   string             `json:"config_ref,omitempty"`
	CheckoutRef string             `json:"checkout_ref,omitempty"`
	Disabled    bool               `json:"disabled"`
}

Trigger represents a CircleCI project trigger.

type TriggerEventSource 

type TriggerEventSource struct {
	Provider string                      `json:"provider"`
	Repo     *TriggerEventSourceRepo     `json:"repo,omitempty"`
	Webhook  *TriggerEventSourceWebhook  `json:"webhook,omitempty"`
	Schedule *TriggerEventSourceSchedule `json:"schedule,omitempty"`
}

TriggerEventSource describes the event source for a trigger.

type TriggerEventSourceRepo 

type TriggerEventSourceRepo struct {
	ExternalID string `json:"external_id"`
	FullName   string `json:"full_name,omitempty"`
}

TriggerEventSourceRepo holds repository information for a trigger event source.

type TriggerEventSourceSchedule 

type TriggerEventSourceSchedule struct {
	Name           string `json:"name,omitempty"`
	CronExpression string `json:"cron_expression,omitempty"`
}

TriggerEventSourceSchedule holds schedule information for a trigger event source.

type TriggerEventSourceWebhook 

type TriggerEventSourceWebhook struct {
	Name   string `json:"name,omitempty"`
	Source string `json:"source,omitempty"`
}

TriggerEventSourceWebhook holds webhook information for a trigger event source. Source is the source system (e.g. "vercel"); Name is the event it sends.

type TriggerPipelineRunInput 

type TriggerPipelineRunInput struct {
	DefinitionID   string
	ConfigBranch   string
	ConfigTag      string
	CheckoutBranch string
	CheckoutTag    string
	Parameters     map[string]any
}

TriggerPipelineRunInput contains the options for triggering a pipeline run.

type TriggerPipelineRunResult 

type TriggerPipelineRunResult struct {
	Triggered bool
	ID        string
	State     string
	Number    int
	CreatedAt time.Time
	Message   string
}

TriggerPipelineRunResult holds the response from triggering a pipeline run. When Triggered is false the pipeline was skipped (e.g. due to a CI skip commit message) and Message describes why.

type TriggerResponse 

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

TriggerResponse is the response body from triggering a pipeline.

type V3Component added in v1.0.47471 

type V3Component struct {
	ID         string           `json:"id"`
	Attributes V3ComponentAttrs `json:"attributes"`
	References V3ComponentRefs  `json:"references"`
}

V3Component represents a deploy component returned by GET /api/v3/deploy/components.

type V3ComponentAttrs added in v1.0.47471 

type V3ComponentAttrs struct {
	Name string `json:"name"`
}

V3ComponentAttrs holds the attributes of a deploy component.

type V3ComponentRefs added in v1.0.47471 

type V3ComponentRefs struct {
	Project struct {
		ID string `json:"id"`
	} `json:"project"`
}

V3ComponentRefs holds reference IDs for a deploy component.

type V3ComponentVersion added in v1.0.47471 

type V3ComponentVersion struct {
	Attributes V3ComponentVersionAttrs `json:"attributes"`
	References V3ComponentVersionRefs  `json:"references"`
}

V3ComponentVersion represents a version of a deploy component.

type V3ComponentVersionAttrs added in v1.0.47471 

type V3ComponentVersionAttrs struct {
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at"`
}

V3ComponentVersionAttrs holds the attributes of a component version.

type V3ComponentVersionRefs added in v1.0.47471 

type V3ComponentVersionRefs struct {
	Component struct {
		ID string `json:"id"`
	} `json:"component"`
}

V3ComponentVersionRefs holds reference IDs for a component version.

type V3DeploySettings added in v1.0.47471 

type V3DeploySettings struct {
	ID         string                `json:"id"`
	Attributes V3DeploySettingsAttrs `json:"attributes"`
	References V3DeploySettingsRefs  `json:"references"`
}

V3DeploySettings represents the deploy settings for a project.

type V3DeploySettingsAttrs added in v1.0.47471 

type V3DeploySettingsAttrs struct{}

V3DeploySettingsAttrs holds the attributes of deploy settings.

type V3DeploySettingsRefs added in v1.0.47471 

type V3DeploySettingsRefs struct {
	Project struct {
		ID string `json:"id"`
	} `json:"project"`
}

V3DeploySettingsRefs holds reference IDs for deploy settings.

type V3Deployment added in v1.0.47331 

type V3Deployment struct {
	ID         string             `json:"id"`
	Attributes v3DeployAttributes `json:"attributes"`
	References v3DeployReferences `json:"references"`
}

V3Deployment represents a deployment returned by GET /api/v3/deploy/deployments.

type V3Environment added in v1.0.47471 

type V3Environment struct {
	ID         string             `json:"id"`
	Attributes V3EnvironmentAttrs `json:"attributes"`
	References V3EnvironmentRefs  `json:"references"`
}

V3Environment represents a deploy environment returned by GET /api/v3/deploy/environments.

type V3EnvironmentAttrs added in v1.0.47471 

type V3EnvironmentAttrs struct {
	Name string `json:"name"`
}

V3EnvironmentAttrs holds the attributes of a deploy environment.

type V3EnvironmentRefs added in v1.0.47471 

type V3EnvironmentRefs struct {
	Organization struct {
		ID string `json:"id"`
	} `json:"org"`
}

V3EnvironmentRefs holds reference IDs for a deploy environment.

type V3Rollback added in v1.0.48275 

type V3Rollback struct {
	ID         string          `json:"id"`
	Attributes V3RollbackAttrs `json:"attributes"`
	References V3RollbackRefs  `json:"references"`
}

V3Rollback is a requested rollback returned by POST /api/v3/projects/{id}/rollback. ID is a handle to the work that carries the rollback out — the pipeline run or the agent command — not an ID minted for the request itself, and RollbackType says which of the two it is.

type V3RollbackAttrs added in v1.0.48275 

type V3RollbackAttrs struct {
	RollbackType string `json:"rollback_type"`
}

V3RollbackAttrs holds the attributes of a requested rollback.

type V3RollbackRefs added in v1.0.48275 

type V3RollbackRefs struct {
	Project struct {
		ID string `json:"id"`
	} `json:"project"`
	DeployComponent struct {
		ID string `json:"id"`
	} `json:"deploy_component"`
	DeployEnvironment struct {
		ID string `json:"id"`
	} `json:"deploy_environment"`
}

V3RollbackRefs holds reference IDs for a requested rollback.

type V3RollbackRequest added in v1.0.48275 

type V3RollbackRequest struct {
	ComponentID    string `json:"component_id"`
	EnvironmentID  string `json:"environment_id"`
	Namespace      string `json:"namespace,omitempty"`
	CurrentVersion string `json:"current_version"`
	TargetVersion  string `json:"target_version"`
	Reason         string `json:"reason,omitempty"`
	// Parameters are passed to the rollback pipeline.
	Parameters map[string]any `json:"parameters,omitempty"`
	// CheckoutRef and ConfigRef select the code and the config the rollback
	// pipeline runs from. Empty means the project's default branch. Both are
	// ignored when the project has no rollback pipeline configured.
	CheckoutRef string `json:"checkout_ref,omitempty"`
	ConfigRef   string `json:"config_ref,omitempty"`
}

V3RollbackRequest is the body of POST /api/v3/projects/{id}/rollback.

The component and the environment are addressed by ID, and Namespace scopes the component within that environment. CurrentVersion is not redundant with TargetVersion: the API rolls back only if the component instance really is running CurrentVersion, so a caller working from stale state cannot roll back a version that has since been superseded.

type VCSCommit 

type VCSCommit struct {
	Subject string `json:"subject"`
	Body    string `json:"body"`
}

VCSCommit holds commit metadata.

type VCSInfo 

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

VCSInfo contains version control information for a project.

type WorkflowJobV3 

type WorkflowJobV3 struct {
	ID             uuid.UUID  `json:"id"`
	Name           string     `json:"name"`
	Phase          string     `json:"phase"`
	Outcome        string     `json:"outcome,omitempty"`
	CurrentOutcome string     `json:"current_outcome,omitempty"`
	Type           string     `json:"type,omitempty"`
	ProjectID      uuid.UUID  `json:"project_id"`
	StartedAt      *time.Time `json:"started_at,omitempty"`
	EndedAt        *time.Time `json:"ended_at,omitempty"`
}

WorkflowJobV3 is a job belonging to a workflow from the V3 API.

func (WorkflowJobV3) Status 

func (w WorkflowJobV3) Status() string

Status derives a display status from phase and outcome.

type WorkflowV3 

type WorkflowV3 struct {
	ID             uuid.UUID  `json:"id"`
	Name           string     `json:"name"`
	Phase          string     `json:"phase"`
	Outcome        string     `json:"outcome,omitempty"`
	CurrentOutcome string     `json:"current_outcome,omitempty"`
	CreatedAt      time.Time  `json:"created_at"`
	EndedAt        *time.Time `json:"ended_at,omitempty"`
	RunID          uuid.UUID  `json:"run_id"`
	ProjectID      uuid.UUID  `json:"project_id"`
}

WorkflowV3 holds workflow detail from the V3 API.

func (WorkflowV3) Status 

func (w WorkflowV3) Status() string

Status derives a display status from phase and outcome.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.