api

package
v3.71.0 Latest Latest
Warning

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

Go to latest
Published: Apr 30, 2024 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:"-"`
}

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

type ArtifactBatchCreateResponse

type ArtifactBatchCreateResponse struct {
	ID                 string                      `json:"id"`
	ArtifactIDs        []string                    `json:"artifact_ids"`
	UploadInstructions *ArtifactUploadInstructions `json:"upload_instructions"`
}

type ArtifactBatchUpdateArtifact

type ArtifactBatchUpdateArtifact struct {
	ID    string `json:"id"`
	State string `json:"state"`
}

type ArtifactBatchUpdateRequest

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

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 ArtifactUploadInstructions

type ArtifactUploadInstructions struct {
	Data   map[string]string `json:"data"`
	Action struct {
		URL       string `json:"url,omitempty"`
		Method    string `json:"method"`
		Path      string `json:"path"`
		FileInput string `json:"file_input"`
	}
}

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

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) 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 map[string]string) (*Response, error)

Updates a particular artifact

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

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

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
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL