apiclient

package
v1.0.47653 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

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

Index

Constants

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 ErrGitHubAppNotInstalled = errors.New("CircleCI GitHub App is not installed for this organization")

ErrGitHubAppNotInstalled is returned by GetGitHubAppInstallation when the CircleCI GitHub App is not installed for the organization (the endpoint answers 404). Callers use it to branch into the install flow.

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 slug.

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"`
	NodeIndex int    `json:"node_index"`
}

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) CompileConfig 

func (c *Client) CompileConfig(ctx context.Context, configYAML, orgID string, previewNext bool, pipelineValues, pipelineParams map[string]any) (*CompileConfigResponse, error)

CompileConfig sends a config YAML to the compilation API and returns the result. Transport failures are returned as errors; API-level validation errors are in the response.

func (*Client) CreateContext 

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

CreateContext creates a new context for the given organization slug.

func (*Client) CreateContextRestriction 

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

CreateContextRestriction adds a project, expression, or group restriction to a context. restrictionType must be one of "project", "expression", or "group". For project restrictions, restrictionValue is the project UUID. For expression restrictions, restrictionValue is the pipeline expression rule. For group restrictions, restrictionValue is the group UUID.

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.

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, resourceClass, description string) (*ResourceClass, error)

CreateResourceClass creates a new runner resource class.

func (*Client) CreateRunnerToken 

func (c *Client) CreateRunnerToken(ctx context.Context, resourceClass, nickname string) (*RunnerToken, error)

CreateRunnerToken creates a new token for the given resource class. The token value is only returned once and is not retrievable afterwards.

func (*Client) CreateTrigger 

func (c *Client) CreateTrigger(ctx context.Context, projectID, pipelineDefinitionID, provider, repoID, eventPreset, configRef, checkoutRef string) (*Trigger, error)

CreateTrigger creates a new trigger for a project's pipeline definition. provider must be one of: github_app, github_server, github_oauth, webhook, schedule. repoID is the repository external ID; required for github_app, github_server, and github_oauth.

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, name string) error

DeleteContextEnvVar removes an environment variable from a context.

func (*Client) DeleteContextRestriction 

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

DeleteContextRestriction removes a restriction from a context by its restriction UUID.

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) error

DeleteResourceClass deletes a runner resource class by its id, along with any tokens issued for it.

func (*Client) DeleteRunnerToken 

func (c *Client) DeleteRunnerToken(ctx context.Context, tokenID string) error

DeleteRunnerToken deletes a runner token by its ID.

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) (*ContextDetail, error)

GetContext returns a context by its UUID.

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) GetGitHubAppInstallation 

func (c *Client) GetGitHubAppInstallation(ctx context.Context, orgID string) (*GitHubAppInstallation, error)

GetGitHubAppInstallation reports the CircleCI GitHub App installation for the organization. orgID must be the organization UUID. It returns ErrGitHubAppNotInstalled when the app is not installed (HTTP 404).

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) 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) 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) 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) GetRunnerTaskCounts 

func (c *Client) GetRunnerTaskCounts(ctx context.Context, resourceClass string) (*RunnerTaskCounts, error)

GetRunnerTaskCounts returns unclaimed and running task counts for a resource class.

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) InitiateGitHubAppInstall 

func (c *Client) InitiateGitHubAppInstall(ctx context.Context, orgID, returnURL string) (string, error)

InitiateGitHubAppInstall starts a GitHub App installation for the organization and returns the URL the user should open to complete the install on GitHub. orgID must be the organization UUID; returnURL is where GitHub redirects after the install completes and must be an app.circleci.com URL.

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 string) ([]ContextEnvVar, error)

ListContextEnvVars returns the environment variable names stored in a context. Values are never returned by the API.

func (*Client) ListContexts 

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

ListContexts returns all contexts owned by the given organization slug (e.g. "gh/myorg"). Paginates automatically.

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) ListGitHubAppRepositories 

func (c *Client) ListGitHubAppRepositories(ctx context.Context, orgID string, page, limit int) ([]GitHubAppRepository, int, error)

ListGitHubAppRepositories returns one page of repositories the GitHub App can access for the organization, along with the total repository count. orgID must be the organization UUID. page is 1-based; limit is the page size (max 100 by the server).

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) ListPipelineDefinitions 

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

ListPipelineDefinitions returns all pipeline definitions for a project.

func (*Client) ListProjects 

func (c *Client) ListProjects(ctx context.Context) ([]Project, error)

ListProjects returns all followed projects for the authenticated user. Uses the v1.1 API.

func (*Client) ListResourceClassesByNamespace 

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

ListResourceClassesByNamespace returns the resource classes for a namespace (organization name). Uses the runner API at runner.circleci.com (or the configured server host).

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. Uses the runner API at runner.circleci.com (or the configured server host).

func (*Client) ListRunnerInstances 

func (c *Client) ListRunnerInstances(ctx context.Context, resourceClass, namespace string) ([]RunnerInstance, error)

ListRunnerInstances returns live runner instances filtered by resource class and/or namespace. Either filter may be empty.

func (*Client) ListRunnerInstancesByOrg 

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

ListRunnerInstancesByOrg returns the live runner instances for an organization, identified by its UUID.

func (*Client) ListRunnerTokens 

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

ListRunnerTokens returns tokens for the given resource class.

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.

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) 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 namespace/name slug. It lists the slug's namespace to find it.

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, name, value string) (*ContextEnvVar, 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) 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) 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) 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 CompileConfigError 

type CompileConfigError struct {
	Message string `json:"message"`
}

CompileConfigError is one entry in a compile response's errors array.

type CompileConfigOptions 

type CompileConfigOptions struct {
	OwnerID            string         `json:"owner_id,omitempty"`
	Next               bool           `json:"next,omitempty"`
	PipelineValues     map[string]any `json:"pipeline_values,omitempty"`
	PipelineParameters map[string]any `json:"pipeline_parameters,omitempty"`
}

CompileConfigOptions controls org ownership and pipeline context for compilation.

type CompileConfigRequest 

type CompileConfigRequest struct {
	ConfigYAML string               `json:"config_yaml"`
	Options    CompileConfigOptions `json:"options"`
}

CompileConfigRequest is sent to POST /api/v2/compile-config-with-defaults.

type CompileConfigResponse 

type CompileConfigResponse struct {
	Valid      bool                 `json:"valid"`
	SourceYAML string               `json:"source-yaml"`
	OutputYAML string               `json:"output-yaml"`
	Errors     []CompileConfigError `json:"errors"`
}

CompileConfigResponse is returned by /api/v2/compile-config-with-defaults.

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 `json:"id"`
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at"`
}

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

type ContextDetail 

type ContextDetail struct {
	ID                   uuid.UUID            `json:"id"`
	Name                 string               `json:"name"`
	CreatedAt            time.Time            `json:"created_at"`
	OrgID                uuid.UUID            `json:"org_id"`
	EnvironmentVariables []ContextEnvVar      `json:"environment_variables"`
	Restrictions         []ContextRestriction `json:"restrictions"`
}

type ContextEnvVar 

type ContextEnvVar struct {
	Variable       string    `json:"variable"`
	TruncatedValue string    `json:"truncated_value"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
	ContextID      uuid.UUID `json:"context_id"`
}

ContextEnvVar is an environment variable stored in a context. The value is never returned by the API.

type ContextRestriction 

type ContextRestriction struct {
	ContextID        uuid.UUID `json:"context_id"`
	ID               uuid.UUID `json:"id"`
	Name             string    `json:"name"`
	RestrictionType  string    `json:"restriction_type"`
	RestrictionValue string    `json:"restriction_value"`
}

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
	ConfigFilePath   string
	CheckoutProvider string
	CheckoutRepoID   string
}

CreatePipelineDefinitionInput contains all fields for creating a pipeline definition.

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 GitHubAppInstallation 

type GitHubAppInstallation struct {
	// ID is the GitHub App installation's external (GitHub) ID.
	ID int64 `json:"id"`
	// TargetType is "Organization" or "User".
	TargetType string `json:"target_type"`
	// Login is the GitHub account the app is installed on.
	Login string `json:"login"`
	// RepositorySelection is "all" or "selected" when present.
	RepositorySelection string `json:"repository_selection,omitempty"`
}

GitHubAppInstallation describes a CircleCI GitHub App installation for an organization, as returned by GET /api/v2/github-app/organization/{orgID}/installation.

type GitHubAppRepository 

type GitHubAppRepository struct {
	// ID is the GitHub numeric repository ID — the external ID used as the repo
	// reference in pipeline definitions and triggers.
	ID int64 `json:"id"`
	// FullName is the "owner/repo" name.
	FullName      string `json:"repo_full_name"`
	Name          string `json:"repo_name"`
	Owner         string `json:"owner"`
	DefaultBranch string `json:"default_branch"`
	Private       bool   `json:"private"`
}

GitHubAppRepository is a repository the CircleCI GitHub App can access, as returned by GET /api/v2/github-app/organization/{orgID}/repositories.

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 {
	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.

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 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"`
	MinorAIFeatures                     bool `json:"enable_minor_ai_features"`
	PrivateOrbs                         bool `json:"enable_private_orbs"`
	UncertifiedPublicOrbs               bool `json:"enable_uncertified_public_orbs"`
	BitbucketWorkspaceMemberIsOrgMember bool `json:"is_bitbucket_workspace_member_org_member"`
	UserCheckoutKeysDisabled            bool `json:"is_user_checkout_keys_disabled"`
	DisableRunning                      bool `json:"is_running_disabled"`
	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.

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"`
	MinorAIFeatures                     *bool `json:"enable_minor_ai_features,omitempty"`
	PrivateOrbs                         *bool `json:"enable_private_orbs,omitempty"`
	UncertifiedPublicOrbs               *bool `json:"enable_uncertified_public_orbs,omitempty"`
	BitbucketWorkspaceMemberIsOrgMember *bool `json:"is_bitbucket_workspace_member_org_member,omitempty"`
	UserCheckoutKeysDisabled            *bool `json:"is_user_checkout_keys_disabled,omitempty"`
	DisableRunning                      *bool `json:"is_running_disabled,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 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 Project 

type Project struct {
	Slug     string `json:"slug"`
	Name     string `json:"name"`
	VCSType  string `json:"vcs_type"`
	Username string `json:"username"`
	RepoName string `json:"reponame"`
}

Project is a followed CircleCI project.

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

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 RunnerInstance 

type RunnerInstance struct {
	ResourceClass  string `json:"resource_class"`
	Hostname       string `json:"hostname"`
	Name           string `json:"name"`
	FirstConnected string `json:"first_connected"`
	LastConnected  string `json:"last_connected"`
	LastUsed       string `json:"last_used"`
	IP             string `json:"ip"`
	Version        string `json:"version"`
}

RunnerInstance is a live runner agent connected to CircleCI.

type RunnerTaskCounts 

type RunnerTaskCounts struct {
	Unclaimed int `json:"unclaimed_task_count"`
	Running   int `json:"running_runner_tasks"`
}

RunnerTaskCounts holds unclaimed and running task counts for a resource class.

type RunnerToken 

type RunnerToken struct {
	ID            string `json:"id"`
	ResourceClass string `json:"resource_class"`
	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 {
	CronExpression string `json:"cron_expression,omitempty"`
}

TriggerEventSourceSchedule holds schedule information for a trigger event source.

type TriggerEventSourceWebhook 

type TriggerEventSourceWebhook struct {
	URL    string `json:"url,omitempty"`
	Sender string `json:"sender,omitempty"`
}

TriggerEventSourceWebhook holds webhook information for a trigger event source.

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 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.