circleci

package
v0.7.162 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const (
	StreamStdout = "stdout"
	StreamStderr = "stderr"
)

Stream names, matching the wire event names.

Variables

View Source 
var ErrNotAuthorized = errors.New("not authorized")

ErrNotAuthorized indicates the request was rejected (401/403).

View Source 
var ErrOutputFormatUnsupported = errors.New("sidecar output format not supported")

ErrOutputFormatUnsupported indicates the output stream contained no events this build understands.

It means the API is *older* than this binary, not newer: the frame vocabulary is designed so a newer API only ever adds event types while still emitting stdout, stderr and exit. Receiving none of those therefore places the API behind the client, which is the opposite of what a naive "upgrade" hint would imply.

View Source 
var ErrTokenNotFound = errors.New("api token not found")

ErrTokenNotFound indicates no CircleCI token was found in env or config.

Functions

func SidecarGone added in v0.7.144 

func SidecarGone(err error) bool

SidecarGone reports whether err is a 404 from an operation addressed at a specific sidecar, meaning that sidecar no longer exists: it was deleted, or it expired server-side.

Only call this on errors from sidecar-scoped requests. A 404 from anything else means a missing route, not a missing sidecar.

func SidecarOutOfDate added in v0.7.144 

func SidecarOutOfDate(err error) bool

SidecarOutOfDate reports whether err is the API refusing to talk to a sidecar because the sidecar itself is too old.

The API returns 410 Gone for two unrelated conditions with opposite remedies: this CLI being too old for the API, and a sidecar being too old for the API. Telling someone to upgrade the CLI when the sidecar is the stale one sends them to a version that fails identically, so the two must be told apart.

Matching on the server's own wording is a compromise: the V3 error envelope carries no machine-readable code, so there is nothing better to key off until the API supplies one.

func SidecarPaused added in v0.7.152 

func SidecarPaused(err error) bool

SidecarPaused reports whether err is the API refusing an operation because the sidecar is suspended. Sidecars pause themselves when left idle.

The underlying sandbox can be resumed: the provider has an API for it, and resume-on-connect is enabled. But the exec path checks the paused state and declines rather than waking it, and no route exposes a resume. So a replacement is the only remedy a caller can act on, however recoverable the sidecar itself may be.

Matched on the server's wording for the same reason as SidecarOutOfDate: the V3 error envelope carries no machine-readable code.

Types

type AddSSHKeyRequest 

type AddSSHKeyRequest struct {
	PublicKey string `json:"public_key"`
}

type AddSSHKeyResponse 

type AddSSHKeyResponse struct {
	URL string `json:"url"`
}

type Client 

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

func NewClient 

func NewClient(cfg Config) (*Client, error)

func (*Client) AddSSHKey 

func (c *Client) AddSSHKey(ctx context.Context, sidecarID, publicKey string) (*AddSSHKeyResponse, error)

func (*Client) CreateOrg added in v0.7.119 

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

CreateOrg creates a new standalone CircleCI organization.

func (*Client) CreateSidecar added in v0.7.31 

func (c *Client) CreateSidecar(ctx context.Context, orgID, name, image string) (*Sidecar, error)

func (*Client) CreateSnapshot added in v0.7.27 

func (c *Client) CreateSnapshot(ctx context.Context, sidecarID, name string) (*Snapshot, error)

func (*Client) DeleteSidecar added in v0.7.43 

func (c *Client) DeleteSidecar(ctx context.Context, sidecarID string) error

func (*Client) Exec 

func (c *Client) Exec(
	ctx context.Context, sidecarID, command string, args []string, env map[string]string, onOutput OutputFn,
) (*ExecResponse, error)

Exec submits a command and collects its output.

When onOutput is non-nil it receives each run of output bytes as it arrives and Stdout/Stderr are left empty — accumulating is then the caller's choice, which matters because output can be arbitrarily large.

func (*Client) GetCommand added in v0.7.97 

func (c *Client) GetCommand(ctx context.Context, commandID string) (*Command, error)

func (*Client) GetCurrentUser added in v0.7.24 

func (c *Client) GetCurrentUser(ctx context.Context) error

GetCurrentUser calls GET /api/v2/me to validate the token.

func (*Client) GetProjectBySlug 

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

GetProjectBySlug fetches project details by slug (e.g. "gh/org/repo").

func (*Client) GetSnapshot added in v0.7.27 

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

func (*Client) ListCollaborations 

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

ListCollaborations returns organizations the user belongs to.

func (*Client) ListFollowedProjects 

func (c *Client) ListFollowedProjects(ctx context.Context) ([]FollowedProject, error)

ListFollowedProjects returns projects the user follows.

func (*Client) ListSidecars added in v0.7.31 

func (c *Client) ListSidecars(ctx context.Context, orgID string, all bool) ([]Sidecar, error)

func (*Client) ListSnapshots added in v0.7.65 

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

func (*Client) PruneSidecars added in v0.7.158 

func (c *Client) PruneSidecars(ctx context.Context, orgID string, before *time.Time) (int, error)

func (*Client) TriggerRun 

func (c *Client) TriggerRun(ctx context.Context, orgID, projectID string, body TriggerRunRequest) (*RunResponse, error)

type Collaboration 

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

Collaboration represents an org the user belongs to.

type Command added in v0.7.97 

type Command struct {
	ID                string  `json:"id"`
	CreatedAt         string  `json:"created_at"`
	EndedAt           *string `json:"ended_at,omitempty"`
	ExitCode          *int    `json:"exit_code,omitempty"`
	Outcome           *string `json:"outcome,omitempty"`
	Phase             string  `json:"phase"`
	SidecarInstanceID string  `json:"sidecar_instance_id"`
}

type Config added in v0.7.29 

type Config struct {
	Token   string
	BaseURL string
	// OnWarn, when non-nil, is called with a plain-text deprecation warning.
	// See httpcl.Config.OnWarn for details.
	OnWarn func(msg string)
}

type ExecRequest 

type ExecRequest struct {
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
}

type ExecResponse 

type ExecResponse struct {
	CommandID string `json:"command_id"`
	PID       int    `json:"pid"`
	Stdout    string `json:"stdout"`
	Stderr    string `json:"stderr"`
	ExitCode  int    `json:"exit_code"`
	// Signal is the symbolic name of the signal that killed the command, empty
	// if it exited normally. When set, ExitCode is 128+signum.
	Signal string `json:"signal,omitempty"`
}

type FollowedProject 

type FollowedProject struct {
	Username string `json:"username"`
	Reponame string `json:"reponame"`
	VcsURL   string `json:"vcs_url"`
	VcsType  string `json:"vcs_type"`
}

FollowedProject represents a project returned by the v1.1 API.

type OrgInfo added in v0.7.119 

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

OrgInfo is the response from POST /api/v2/organization.

type OutputFn added in v0.7.132 

type OutputFn func(stream string, data []byte)

OutputFn receives a run of raw output bytes from one stream, exactly as the remote command wrote them. data is only valid for the duration of the call.

type ProjectDetail 

type ProjectDetail struct {
	ID    string `json:"id"`
	Slug  string `json:"slug"`
	Name  string `json:"name"`
	OrgID string `json:"org_id"`
}

ProjectDetail represents detailed project info from the v2 API.

type RunResponse 

type RunResponse struct {
	RunID      string `json:"runId,omitempty"`
	PipelineID string `json:"pipelineId,omitempty"`
}

type Sidecar added in v0.7.31 

type Sidecar struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	OrgID string `json:"org_id"`
	Image string `json:"image,omitempty"`
}

type Snapshot added in v0.7.27 

type Snapshot struct {
	ID    string `json:"id"`
	OrgID string `json:"org_id"`
	Name  string `json:"name"`
	Tag   string `json:"tag,omitempty"`
	// IsSystem marks a CircleCI-provided base snapshot rather than one an org
	// captured itself. Snapshot selection prefers an org's own snapshot when
	// both match a repo equally well.
	IsSystem bool `json:"is_system,omitempty"`
}

type StatusError added in v0.7.29 

type StatusError = hc.StatusError

StatusError is an alias for the shared httpcl.StatusError type.

type TriggerRunRequest 

type TriggerRunRequest struct {
	AgentType          string                 `json:"agent_type"`
	DefinitionID       string                 `json:"definition_id"`
	CheckoutBranch     string                 `json:"checkout_branch"`
	TriggerSource      string                 `json:"trigger_source"`
	TriggerType        string                 `json:"trigger_type"`
	ChunkEnvironmentID *string                `json:"chunk_environment_id,omitempty"`
	Parameters         map[string]interface{} `json:"parameters"`
	Stats              *TriggerRunStats       `json:"stats,omitempty"`
}

type TriggerRunStats 

type TriggerRunStats struct {
	Prompt         string `json:"prompt"`
	CheckoutBranch string `json:"checkout_branch"`
}

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.