api

package
v3.92.1 Latest Latest
Warning

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

 Go to latest Published: Feb 13, 2025 License: MIT Imports: 24 Imported by: 3

Documentation

Overview

Package api provides an API client for the Buildkite Pipelines API.

It is intended for internal use by buildkite-agent only.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsErrHavingStatus added in v3.44.0 

func IsErrHavingStatus(err error, code int) bool

func IsRetryableError 

func IsRetryableError(err error) bool

Looks at a bunch of connection related errors, and returns true if the error matches one of them.

func IsRetryableStatus added in v3.40.0 

func IsRetryableStatus(r *Response) bool

IsRetryableStatus returns true if the response's StatusCode is one that we should retry.

func NewUUID 

func NewUUID() string

Types

type AgentRegisterRequest 

type AgentRegisterRequest struct {
	Name               string   `json:"name"`
	Hostname           string   `json:"hostname"`
	OS                 string   `json:"os"`
	Arch               string   `json:"arch"`
	ScriptEvalEnabled  bool     `json:"script_eval_enabled"`
	IgnoreInDispatches bool     `json:"ignore_in_dispatches"`
	Priority           string   `json:"priority,omitempty"`
	Version            string   `json:"version"`
	Build              string   `json:"build"`
	Tags               []string `json:"meta_data"`
	PID                int      `json:"pid,omitempty"`
	MachineID          string   `json:"machine_id,omitempty"`
	Features           []string `json:"features"`
}

AgentRegisterRequest is a call to register on the Buildkite Agent API

type AgentRegisterResponse 

type AgentRegisterResponse struct {
	UUID              string   `json:"id"`
	Name              string   `json:"name"`
	AccessToken       string   `json:"access_token"`
	Endpoint          string   `json:"endpoint"`
	PingInterval      int      `json:"ping_interval"`
	JobStatusInterval int      `json:"job_status_interval"`
	HeartbeatInterval int      `json:"heartbeat_interval"`
	Tags              []string `json:"meta_data"`
}

AgentRegisterResponse is the response from the Buildkite Agent API

type Annotation 

type Annotation struct {
	Body     string `json:"body,omitempty"`
	Context  string `json:"context,omitempty"`
	Style    string `json:"style,omitempty"`
	Append   bool   `json:"append,omitempty"`
	Priority int    `json:"priority,omitempty"`
}

Annotation represents a Buildkite Agent API Annotation

type Artifact 

type Artifact struct {
	// The ID of the artifact. The ID is assigned to it after a successful
	// batch creation
	ID string `json:"id"`

	// The path to the artifact relative to the working directory
	Path string `json:"path"`

	// The absolute path to the artifact
	AbsolutePath string `json:"absolute_path"`

	// The glob path used to find this artifact
	GlobPath string `json:"glob_path"`

	// The size of the file in bytes
	FileSize int64 `json:"file_size"`

	// A SHA-1 hash of the uploaded file
	Sha1Sum string `json:"sha1sum"`

	// A SHA-2 256-bit hash of the uploaded file, possibly empty
	Sha256Sum string `json:"sha256sum"`

	// ID of the job that created this artifact (from API)
	JobID string `json:"job_id"`

	// UTC timestamp this artifact was considered created
	CreatedAt time.Time `json:"created_at"`

	// The HTTP url to this artifact once it's been uploaded
	URL string `json:"url,omitempty"`

	// The destination specified on the command line when this file was
	// uploaded
	UploadDestination string `json:"upload_destination,omitempty"`

	// Information on how to upload this artifact.
	UploadInstructions *ArtifactUploadInstructions `json:"-"`

	// A specific Content-Type to use on upload
	ContentType string `json:"content_type,omitempty"`
}

Artifact represents an artifact on the Buildkite Agent API

type ArtifactBatch 

type ArtifactBatch struct {
	ID                 string      `json:"id"`
	Artifacts          []*Artifact `json:"artifacts"`
	UploadDestination  string      `json:"upload_destination"`
	MultipartSupported bool        `json:"multipart_supported,omitempty"`
}

type ArtifactBatchCreateResponse 

type ArtifactBatchCreateResponse struct {
	ID          string   `json:"id"`
	ArtifactIDs []string `json:"artifact_ids"`

	// These instructions apply to all artifacts. The template contains
	// variable interpolations such as ${artifact:path}.
	InstructionsTemplate *ArtifactUploadInstructions `json:"upload_instructions"`

	// These instructions apply to specific artifacts, necessary for multipart
	// uploads. It overrides InstructionTemplate and should not contain
	// interpolations. Map: artifact ID -> instructions for that artifact.
	PerArtifactInstructions map[string]*ArtifactUploadInstructions `json:"per_artifact_instructions"`
}

type ArtifactBatchUpdateRequest 

type ArtifactBatchUpdateRequest struct {
	Artifacts []ArtifactState `json:"artifacts"`
}

type ArtifactPartETag added in v3.83.0 

type ArtifactPartETag struct {
	PartNumber int    `json:"part_number"`
	ETag       string `json:"etag"`
}

ArtifactPartETag associates an ETag to a part number for a multipart upload.

type ArtifactSearchOptions 

type ArtifactSearchOptions struct {
	Query              string `url:"query,omitempty"`
	Scope              string `url:"scope,omitempty"`
	State              string `url:"state,omitempty"`
	IncludeRetriedJobs bool   `url:"include_retried_jobs,omitempty"`
	IncludeDuplicates  bool   `url:"include_duplicates,omitempty"`
}

ArtifactSearchOptions specifies the optional parameters to the ArtifactsService.Search method.

type ArtifactState added in v3.83.0 

type ArtifactState struct {
	ID        string `json:"id"`
	State     string `json:"state"`
	Multipart bool   `json:"multipart,omitempty"`
	// If this artifact was a multipart upload and is complete, we need the
	// the ETag from each uploaded part so that they can be joined together.
	MultipartETags []ArtifactPartETag `json:"multipart_etags,omitempty"`
}

ArtifactState represents the state of a single artifact, when calling UpdateArtifacts.

type ArtifactUploadAction added in v3.83.0 

type ArtifactUploadAction struct {
	URL        string `json:"url,omitempty"`
	Method     string `json:"method"`
	Path       string `json:"path"`
	FileInput  string `json:"file_input"`
	PartNumber int    `json:"part_number,omitempty"`
}

ArtifactUploadAction describes one action needed to upload an artifact or part of an artifact to Buildkite artifact storage.

type ArtifactUploadInstructions 

type ArtifactUploadInstructions struct {
	// Used for a single-part upload.
	Action ArtifactUploadAction `json:"action"`

	// Used for a multi-part upload.
	Actions []ArtifactUploadAction `json:"actions"`

	// Contains other data necessary for interpreting instructions.
	Data map[string]string `json:"data"`
}

ArtifactUploadInstructions describes how to upload an artifact to Buildkite artifact storage.

type Build added in v3.84.0 

type Build struct {
	UUID string `json:"uuid"`
}

type Chunk 

type Chunk struct {
	Data     []byte
	Sequence uint64
	Offset   uint64
	Size     uint64
}

Chunk represents a Buildkite Agent API Chunk

type Client 

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

A Client manages communication with the Buildkite Agent API.

func NewClient 

func NewClient(l logger.Logger, conf Config) *Client

NewClient returns a new Buildkite Agent API Client.

func (*Client) AcceptJob 

func (c *Client) AcceptJob(ctx context.Context, job *Job) (*Job, *Response, error)

AcceptJob accepts the passed in job. Returns the job with its finalized set of environment variables (when a job is accepted, the agents environment is applied to the job)

func (*Client) AcquireJob 

func (c *Client) AcquireJob(ctx context.Context, id string, headers ...Header) (*Job, *Response, error)

Acquires a job using its ID

func (*Client) Annotate 

func (c *Client) Annotate(ctx context.Context, jobId string, annotation *Annotation) (*Response, error)

Annotate a build in the Buildkite UI

func (*Client) AnnotationRemove added in v3.28.1 

func (c *Client) AnnotationRemove(ctx context.Context, jobId string, context string) (*Response, error)

Remove an annotation from a build

func (*Client) CancelBuild added in v3.84.0 

func (c *Client) CancelBuild(ctx context.Context, uuid string) (*Build, *Response, error)

CancelBuild cancels a build with the given UUID

func (*Client) Config 

func (c *Client) Config() Config

Config returns the internal configuration for the Client

func (*Client) Connect 

func (c *Client) Connect(ctx context.Context) (*Response, error)

Connects the agent to the Buildkite Agent API

func (*Client) CreateArtifacts 

func (c *Client) CreateArtifacts(ctx context.Context, jobID string, batch *ArtifactBatch) (*ArtifactBatchCreateResponse, *Response, error)

CreateArtifacts takes a slice of artifacts, and creates them on Buildkite as a batch.

func (*Client) Disconnect 

func (c *Client) Disconnect(ctx context.Context) (*Response, error)

Disconnects the agent to the Buildkite Agent API

func (*Client) ExistsMetaData 

func (c *Client) ExistsMetaData(ctx context.Context, scope, id, key string) (*MetaDataExists, *Response, error)

Returns true if the meta data key has been set, false if it hasn't.

func (*Client) FinishJob 

func (c *Client) FinishJob(ctx context.Context, job *Job) (*Response, error)

FinishJob finishes the passed in job

func (*Client) FromAgentRegisterResponse 

func (c *Client) FromAgentRegisterResponse(resp *AgentRegisterResponse) *Client

FromAgentRegisterResponse returns a new instance using the access token and endpoint from the registration response

func (*Client) FromPing 

func (c *Client) FromPing(resp *Ping) *Client

FromPing returns a new instance using a new endpoint from a ping response

func (*Client) GenerateGithubCodeAccessToken added in v3.63.0 

func (c *Client) GenerateGithubCodeAccessToken(ctx context.Context, repoURL, jobID string) (string, *Response, error)

func (*Client) GetJobState 

func (c *Client) GetJobState(ctx context.Context, id string) (*JobState, *Response, error)

GetJobState returns the state of a given job

func (*Client) GetMetaData 

func (c *Client) GetMetaData(ctx context.Context, scope, id, key string) (*MetaData, *Response, error)

Gets the meta data value

func (*Client) GetSecret added in v3.64.0 

func (c *Client) GetSecret(ctx context.Context, req *GetSecretRequest) (*Secret, *Response, error)

GetSecret reads a secret from the Buildkite Agent API.

func (*Client) Heartbeat 

func (c *Client) Heartbeat(ctx context.Context) (*Heartbeat, *Response, error)

Heartbeat notifies Buildkite that an agent is still connected

func (*Client) MetaDataKeys 

func (c *Client) MetaDataKeys(ctx context.Context, scope, id string) ([]string, *Response, error)

func (*Client) OIDCToken added in v3.41.0 

func (c *Client) OIDCToken(ctx context.Context, methodReq *OIDCTokenRequest) (*OIDCToken, *Response, error)

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) (*Ping, *Response, error)

Pings the API and returns any work the client needs to perform

func (*Client) PipelineUploadStatus added in v3.44.0 

func (c *Client) PipelineUploadStatus(
	ctx context.Context,
	jobId string,
	uuid string,
	headers ...Header,
) (*PipelineUploadStatus, *Response, error)

func (*Client) Register 

func (c *Client) Register(ctx context.Context, regReq *AgentRegisterRequest) (*AgentRegisterResponse, *Response, error)

Registers the agent against the Buildkite Agent API. The client for this call must be authenticated using an Agent Registration Token

func (*Client) SaveHeaderTimes 

func (c *Client) SaveHeaderTimes(ctx context.Context, jobId string, headerTimes *HeaderTimes) (*Response, error)

SaveHeaderTimes saves the header times to the job

func (*Client) SearchArtifacts 

func (c *Client) SearchArtifacts(ctx context.Context, buildID string, opt *ArtifactSearchOptions) ([]*Artifact, *Response, error)

SearchArtifacts searches Buildkite for a set of artifacts

func (*Client) SetMetaData 

func (c *Client) SetMetaData(ctx context.Context, jobId string, metaData *MetaData) (*Response, error)

Sets the meta data value

func (*Client) StartJob 

func (c *Client) StartJob(ctx context.Context, job *Job) (*Response, error)

StartJob starts the passed in job

func (*Client) StepCancel added in v3.85.0 

func (c *Client) StepCancel(ctx context.Context, stepIdOrKey string, stepCancel *StepCancel) (*StepCancelResponse, *Response, error)

StepCancel cancels a step

func (*Client) StepExport 

func (c *Client) StepExport(ctx context.Context, stepIdOrKey string, stepGetRequest *StepExportRequest) (*StepExportResponse, *Response, error)

StepExport gets an attribute from step

func (*Client) StepUpdate 

func (c *Client) StepUpdate(ctx context.Context, stepIdOrKey string, stepUpdate *StepUpdate) (*Response, error)

StepUpdate updates a step

func (*Client) UpdateArtifacts 

func (c *Client) UpdateArtifacts(ctx context.Context, jobID string, artifactStates []ArtifactState) (*Response, error)

UpdateArtifacts updates Buildkite with one or more artifact states.

func (*Client) UploadChunk 

func (c *Client) UploadChunk(ctx context.Context, jobId string, chunk *Chunk) (*Response, error)

Uploads the chunk to the Buildkite Agent API. This request sends the compressed log directly as a request body.

func (*Client) UploadPipeline 

func (c *Client) UploadPipeline(
	ctx context.Context,
	jobId string,
	pipeline *PipelineChange,
	headers ...Header,
) (*Response, error)

UploadPipeline uploads the pipeline to the Buildkite Agent API. It does not wait for the pipeline to finish processing but will instead return with a redirect to the location to check the pipeline's status.

type Config 

type Config struct {
	// Endpoint for API requests. Defaults to the public Buildkite Agent API.
	// The URL should always be specified with a trailing slash.
	Endpoint string

	// The authentication token to use, either a registration or access token
	Token string

	// User agent used when communicating with the Buildkite Agent API.
	UserAgent string

	// If true, only HTTP2 is disabled
	DisableHTTP2 bool

	// If true, requests and responses will be dumped and set to the logger
	DebugHTTP bool

	// If true timings for each request will be logged
	TraceHTTP bool

	// The http client used, leave nil for the default
	HTTPClient *http.Client

	// optional TLS configuration primarily used for testing
	TLSConfig *tls.Config
}

Config is configuration for the API Client

type ErrorResponse 

type ErrorResponse struct {
	Response *http.Response // HTTP response that caused this error
	Message  string         `json:"message"` // error message
}

ErrorResponse provides a message.

func (*ErrorResponse) Error 

func (r *ErrorResponse) Error() string

type GetSecretRequest added in v3.64.0 

type GetSecretRequest struct {
	Key   string
	JobID string
}

GetSecretRequest represents a request to read a secret from the Buildkite Agent API.

type GithubCodeAccessTokenRequest added in v3.63.0 

type GithubCodeAccessTokenRequest struct {
	RepoURL string `json:"repo_url,omitempty"`
}

type GithubCodeAccessTokenResponse added in v3.63.0 

type GithubCodeAccessTokenResponse struct {
	Token string `json:"token,omitempty"`
}
type Header struct {
	Name  string
	Value string
}

type HeaderTimes 

type HeaderTimes struct {
	Times map[string]string `json:"header_times"`
}

HeaderTimes represents a set of header times that are associated with a job log.

type Heartbeat 

type Heartbeat struct {
	SentAt     string `json:"sent_at"`
	ReceivedAt string `json:"received_at,omitempty"`
}

Heartbeat represents a Buildkite Agent API Heartbeat

type Job 

type Job struct {
	ID                 string                     `json:"id,omitempty"`
	Endpoint           string                     `json:"endpoint"`
	State              string                     `json:"state,omitempty"`
	Env                map[string]string          `json:"env,omitempty"`
	Step               pipeline.CommandStep       `json:"step,omitempty"`
	MatrixPermutation  pipeline.MatrixPermutation `json:"matrix_permutation,omitempty"`
	ChunksMaxSizeBytes uint64                     `json:"chunks_max_size_bytes,omitempty"`
	LogMaxSizeBytes    uint64                     `json:"log_max_size_bytes,omitempty"`
	Token              string                     `json:"token,omitempty"`
	ExitStatus         string                     `json:"exit_status,omitempty"`
	Signal             string                     `json:"signal,omitempty"`
	SignalReason       string                     `json:"signal_reason,omitempty"`
	StartedAt          string                     `json:"started_at,omitempty"`
	FinishedAt         string                     `json:"finished_at,omitempty"`
	RunnableAt         string                     `json:"runnable_at,omitempty"`
	ChunksFailedCount  int                        `json:"chunks_failed_count,omitempty"`
}

Job represents a Buildkite Agent API Job

type JobState 

type JobState struct {
	State string `json:"state,omitempty"`
}

type MetaData 

type MetaData struct {
	Key   string `json:"key,omitempty"`
	Value string `json:"value,omitempty"`
}

MetaData represents a Buildkite Agent API MetaData

type MetaDataExists 

type MetaDataExists struct {
	Exists bool `json:"exists"`
}

MetaDataExists represents a Buildkite Agent API MetaData Exists check response

type OIDCToken added in v3.41.0 

type OIDCToken struct {
	Token string `json:"token"`
}

type OIDCTokenRequest added in v3.41.0 

type OIDCTokenRequest struct {
	Job            string
	Audience       string
	Lifetime       int
	Claims         []string
	AWSSessionTags []string
}

type Ping 

type Ping struct {
	Action   string `json:"action,omitempty"`
	Message  string `json:"message,omitempty"`
	Job      *Job   `json:"job,omitempty"`
	Endpoint string `json:"endpoint,omitempty"`
}

Ping represents a Buildkite Agent API Ping

type PipelineChange added in v3.44.0 

type PipelineChange struct {
	// UUID identifies this pipeline change. We keep this constant during
	// retry loops so that work is not repeated on the API server
	UUID     string `json:"uuid"`
	Pipeline any    `json:"pipeline"`
	Replace  bool   `json:"replace,omitempty"`
}

PipelineChange represents a Buildkite Agent API PipelineChange

type PipelineUploadStatus added in v3.44.0 

type PipelineUploadStatus struct {
	State   string `json:"state"`
	Message string `json:"message"`
}

type Response 

type Response struct {
	*http.Response
}

Response is a Buildkite Agent API response. This wraps the standard http.Response.

type Secret added in v3.64.0 

type Secret struct {
	Key   string `json:"key"`
	Value string `json:"value"`
	UUID  string `json:"uuid"`
}

Secret represents a secret read from the Buildkite Agent API.

type StepCancel added in v3.85.0 

type StepCancel struct {
	Build                   string `json:"build_id"`
	Force                   bool   `json:"force"`
	ForceGracePeriodSeconds int64  `json:"force_grace_period"`
}

type StepCancelResponse added in v3.85.0 

type StepCancelResponse struct {
	UUID string `json:"uuid"`
}

type StepExportRequest 

type StepExportRequest struct {
	Attribute string `json:"attribute,omitempty"`
	Build     string `json:"build_id,omitempty"`
	Format    string `json:"format,omitempty"`
}

StepExportRequest represents a request for information about a step

type StepExportResponse 

type StepExportResponse struct {
	Output string `json:"output"`
}

type StepUpdate 

type StepUpdate struct {
	IdempotencyUUID string `json:"idempotency_uuid,omitempty"`
	Build           string `json:"build_id,omitempty"`
	Attribute       string `json:"attribute,omitempty"`
	Value           string `json:"value,omitempty"`
	Append          bool   `json:"append,omitempty"`
}

StepUpdate represents a change request to a step

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.