apiclient

package
v1.0.40468-pre Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

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 ErrNamespaceNotFound = errors.New("namespace not found")

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

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.

Functions

func BuildRunFilter 

func BuildRunFilter(branch, status string) string

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

func PhaseOutcomeStatus 

func PhaseOutcomeStatus(phase, outcome, currentOutcome string) string

PhaseOutcomeStatus derives a human-readable status string from V3 phase, outcome, and current_outcome fields.

func UserAgent 

func UserAgent(goos, goarch, version, agent string) string

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 an authenticated CircleCI API client.

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

func (c *Client) CancelWorkflow(ctx context.Context, id string) 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, 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, name, certID string, profiles []IOSProvisioningProfile) (string, 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) 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 string) 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 string) 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, resourceClass string) error

DeleteResourceClass deletes a runner resource class by its namespace/name slug.

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, policyName 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) 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) 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) GetJob 

func (c *Client) GetJob(ctx context.Context, projectSlug string, jobNumber int64) (*Job, error)

GetJob fetches full job details including steps and their output URLs. The v2 API returns job metadata but often omits step output; if steps are absent, GetJob transparently retries against the v1.1 API which always includes step output.

func (*Client) GetJobArtifacts 

func (c *Client) GetJobArtifacts(ctx context.Context, projectSlug string, jobNumber int64) ([]Artifact, error)

GetJobArtifacts returns the artifacts produced by a specific job number within a project.

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

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

GetJobV3 fetches job detail from the V3 API by UUID.

func (*Client) GetLatestPipeline 

func (c *Client) GetLatestPipeline(ctx context.Context, projectSlug, branch string) (*Pipeline, error)

GetLatestPipeline returns the most recent pipeline for the given project slug and branch. Pass an empty branch to get the latest pipeline regardless of branch.

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

func (c *Client) GetOrg(ctx context.Context, slugOrID string) (*OrgInfo, error)

GetOrg fetches an organization by its slug or UUID.

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

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

GetProjectInfo returns detailed information about a project by slug.

func (*Client) GetRunV3 

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

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

func (*Client) GetRunWorkflowsV3 

func (c *Client) GetRunWorkflowsV3(ctx context.Context, runID string) ([]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) GetWorkflowJobs 

func (c *Client) GetWorkflowJobs(ctx context.Context, workflowID string) ([]WorkflowJob, error)

GetWorkflowJobs returns all jobs belonging to a workflow via V2.

func (*Client) GetWorkflowJobsV3 

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

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

func (*Client) GetWorkflowV3 

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

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

func (*Client) ListCollaborations 

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

ListCollaborations returns the organizations the authenticated user belongs to.

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

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

ListDeploys returns up to limit deploys for a project. It paginates the API automatically until the limit is reached or all results are exhausted. 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) ListIOSCertificates 

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

ListIOSCertificates returns the certificates stored for the given org.

func (*Client) ListIOSSigningConfigs 

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

ListIOSSigningConfigs returns the signing configs stored for the given org.

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

func (*Client) SearchRunsV3 

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

SearchRunsV3 searches for runs using the V3 search endpoint.

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

func (c *Client) UploadIOSCertificate(ctx context.Context, orgID, fileName, blob, password string) (string, 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"`
	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
}

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 Deploy 

type Deploy struct {
	ID             string    `json:"id"`
	ProjectID      string    `json:"project_id"`
	ComponentID    string    `json:"component_id"`
	ComponentName  string    `json:"component_name"`
	Type           string    `json:"type"`
	Status         string    `json:"status"`
	TargetVersion  *Version  `json:"target_version"`
	PipelineID     string    `json:"pipeline_id,omitempty"`
	WorkflowID     string    `json:"workflow_id,omitempty"`
	PlanIsRollback bool      `json:"plan_is_rollback"`
	IsRedeploy     bool      `json:"is_rerelease"`
	FailureReason  string    `json:"failure_reason,omitempty"`
	CreatedAt      time.Time `json:"created_at"`
	StartedAt      time.Time `json:"started_at"`
	EndedAt        time.Time `json:"ended_at"`
}

Deploy represents a deploy returned by the CircleCI Deploy API.

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 IOSCertificate 

type IOSCertificate struct {
	ID       string `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. Shape matches the ciam-gateway list response.

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 — no UUID.

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                   string                   `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. Shape matches the ciam-gateway list response — the certificate is returned as a nested object (file_name + cert_type only); the cert UUID is not echoed back in list output.

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         string           `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  string           `json:"project_id"`
	PipelineID string           `json:"pipeline_id"`
	WorkflowID string           `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 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 GET /api/v2/organization/{slug-or-id}.

type Pipeline 

type Pipeline struct {
	ID                string                     `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 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 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 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             string     `json:"id"`
	Phase          string     `json:"phase"`
	Outcome        string     `json:"outcome,omitempty"`
	CurrentOutcome string     `json:"current_outcome,omitempty"`
	Branch         string     `json:"branch,omitempty"`
	Revision       string     `json:"revision,omitempty"`
	CreatedAt      time.Time  `json:"created_at"`
	ProjectID      string     `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 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 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 Version 

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

Version holds a version name.

type WorkflowJob 

type WorkflowJob struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	JobNumber   int64     `json:"job_number"`
	Status      string    `json:"status"`
	Type        string    `json:"type"`
	ProjectSlug string    `json:"project_slug"`
	StartedAt   time.Time `json:"started_at"`
	StoppedAt   time.Time `json:"stopped_at"`
}

WorkflowJob is a job belonging to a workflow (V2 API). Used by artifacts and logs which need JobNumber and ProjectSlug.

type WorkflowJobV3 

type WorkflowJobV3 struct {
	ID             string     `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      string     `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             string     `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          string     `json:"run_id"`
	ProjectID      string     `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.