Documentation
¶
Overview ¶
Package api provides an API client for the Buildkite Pipelines API.
It is intended for internal use by buildkite-agent only.
Index ¶
- func IsErrHavingStatus(err error, code int) bool
- func IsRetryableError(err error) bool
- func IsRetryableStatus(r *Response) bool
- func NewUUID() string
- type AgentRegisterRequest
- type AgentRegisterResponse
- type Annotation
- type Artifact
- type ArtifactBatch
- type ArtifactBatchCreateResponse
- type ArtifactBatchUpdateArtifact
- type ArtifactBatchUpdateRequest
- type ArtifactSearchOptions
- type ArtifactUploadInstructions
- type Chunk
- type Client
- func (c *Client) AcceptJob(ctx context.Context, job *Job) (*Job, *Response, error)
- func (c *Client) AcquireJob(ctx context.Context, id string, headers ...Header) (*Job, *Response, error)
- func (c *Client) Annotate(ctx context.Context, jobId string, annotation *Annotation) (*Response, error)
- func (c *Client) AnnotationRemove(ctx context.Context, jobId string, context string) (*Response, error)
- func (c *Client) Config() Config
- func (c *Client) Connect(ctx context.Context) (*Response, error)
- func (c *Client) CreateArtifacts(ctx context.Context, jobId string, batch *ArtifactBatch) (*ArtifactBatchCreateResponse, *Response, error)
- func (c *Client) Disconnect(ctx context.Context) (*Response, error)
- func (c *Client) ExistsMetaData(ctx context.Context, scope, id, key string) (*MetaDataExists, *Response, error)
- func (c *Client) FinishJob(ctx context.Context, job *Job) (*Response, error)
- func (c *Client) FromAgentRegisterResponse(resp *AgentRegisterResponse) *Client
- func (c *Client) FromPing(resp *Ping) *Client
- func (c *Client) GetJobState(ctx context.Context, id string) (*JobState, *Response, error)
- func (c *Client) GetMetaData(ctx context.Context, scope, id, key string) (*MetaData, *Response, error)
- func (c *Client) Heartbeat(ctx context.Context) (*Heartbeat, *Response, error)
- func (c *Client) MetaDataKeys(ctx context.Context, scope, id string) ([]string, *Response, error)
- func (c *Client) OIDCToken(ctx context.Context, methodReq *OIDCTokenRequest) (*OIDCToken, *Response, error)
- func (c *Client) Ping(ctx context.Context) (*Ping, *Response, error)
- func (c *Client) PipelineUploadStatus(ctx context.Context, jobId string, uuid string, headers ...Header) (*PipelineUploadStatus, *Response, error)
- func (c *Client) Register(ctx context.Context, regReq *AgentRegisterRequest) (*AgentRegisterResponse, *Response, error)
- func (c *Client) SaveHeaderTimes(ctx context.Context, jobId string, headerTimes *HeaderTimes) (*Response, error)
- func (c *Client) SearchArtifacts(ctx context.Context, buildId string, opt *ArtifactSearchOptions) ([]*Artifact, *Response, error)
- func (c *Client) SetMetaData(ctx context.Context, jobId string, metaData *MetaData) (*Response, error)
- func (c *Client) StartJob(ctx context.Context, job *Job) (*Response, error)
- func (c *Client) StepExport(ctx context.Context, stepIdOrKey string, stepGetRequest *StepExportRequest) (*StepExportResponse, *Response, error)
- func (c *Client) StepUpdate(ctx context.Context, stepIdOrKey string, stepUpdate *StepUpdate) (*Response, error)
- func (c *Client) UpdateArtifacts(ctx context.Context, jobId string, artifactStates map[string]string) (*Response, error)
- func (c *Client) UploadChunk(ctx context.Context, jobId string, chunk *Chunk) (*Response, error)
- func (c *Client) UploadPipeline(ctx context.Context, jobId string, pipeline *PipelineChange, headers ...Header) (*Response, error)
- type Config
- type ErrorResponse
- type Header
- type HeaderTimes
- type Heartbeat
- type Job
- type JobState
- type MetaData
- type MetaDataExists
- type OIDCToken
- type OIDCTokenRequest
- type Ping
- type PipelineChange
- type PipelineUploadStatus
- type Response
- type StepExportRequest
- type StepExportResponse
- type StepUpdate
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsErrHavingStatus ¶ added in v3.44.0
func IsRetryableError ¶
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
IsRetryableStatus returns true if the response's StatusCode is one that we should retry.
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"`
}
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 ArtifactBatchCreateResponse ¶
type ArtifactBatchCreateResponse struct {
ID string `json:"id"`
ArtifactIDs []string `json:"artifact_ids"`
UploadInstructions *ArtifactUploadInstructions `json:"upload_instructions"`
}
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 Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client manages communication with the Buildkite Agent API.
func (*Client) AcceptJob ¶
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) 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 ¶
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) 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) GetJobState ¶
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) MetaDataKeys ¶
func (*Client) PipelineUploadStatus ¶ added in v3.44.0
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) 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 ¶
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 HeaderTimes ¶
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"`
ChunksMaxSizeBytes int `json:"chunks_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 MetaDataExists ¶
type MetaDataExists struct {
Exists bool `json:"exists"`
}
MetaDataExists represents a Buildkite Agent API MetaData Exists check response
type OIDCTokenRequest ¶ added in v3.41.0
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 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