githubactions

package
v0.3.0-20260814204056-... Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

README

GitHub Actions client

Shared HTTP client and GitHub Actions-specific facts for every domain's GitHub Actions-backed BuildRunner. There is no BuildRunner interface here by design — each domain (submitqueue, stovepipe, ...) defines its own BuildRunner and its own BuildStatus, and adapts this package's RunStatus to it. Mirrors platform/buildkite's split; see that package's README and doc/rfc/stovepipe/steps/build.md for the shared rationale.

What lives here

  • Client: DispatchWorkflow / GetRun / CancelRun against the GitHub Actions REST API, bound to a single repository and workflow. Construct one with NewClient(httpClient, owner, repo, workflowID), where httpClient already has the GitHub API root (via platform/http.BaseURLTransport, typically https://api.github.com) and a token with actions:read/actions:write configured.
  • RunStatus / ParseRunStatus: GitHub's own run status/conclusion vocabulary (queued/in_progress/completed crossed with a conclusion), collapsed into the five states every domain's BuildStatus already distinguishes. Each domain still does its own trivial RunStatus → its own BuildStatus switch — this package does not know either domain's entity types.
  • EncodeRunID / ParseRunID: the run-id-as-build-id convention, mirroring Buildkite's build-number encoding.
  • RunMetadata: builds the caller-facing metadata map (run id, attempt, status, conclusion, title, URL, branch, created-at) from a WorkflowRun.

Who consumes it

  • submitqueue/extension/buildrunner/githubactions — batch-identity BuildRunner, resolves changes via changeset.Resolver before dispatching.
  • stovepipe/extension/buildrunner/githubactions — URI-identity BuildRunner, dispatches directly from headURI/baseURI.

Both wrap a *Client built at the wiring layer; this package never constructs one from raw config (no credentials, no repo/workflow) itself.

How the same Client stays safe to share across two different checkout strategies

As with the Buildkite client, Client.DispatchWorkflow never inspects DispatchWorkflowRequest.Inputs or picks a strategy — the split happens entirely outside this package:

  1. Each domain's own adapter shapes a different Inputs payload. SubmitQueue's runner sends sq_base_uris/sq_head_uris as JSON-encoded arrays of resolved change URIs; stovepipe's sends stovepipe_head_uri/stovepipe_base_uri as single plain strings. Both just call Client.DispatchWorkflow with their own Inputs map — this package treats it as an opaque map[string]string.
  2. Each domain's Client targets a different repository/workflow, bound once at wiring time via NewClient's owner/repo/workflowID arguments. Each workflow file (owned by the target repository, outside this package) is written against its domain's input contract — one applies patches into composite commits, the other checks out stovepipe_head_uri and diffs against stovepipe_base_uri.

So the checkout strategy is a static, wiring-time binding — one Client instance ↔ one repo/workflow ↔ one workflow definition ↔ one input contract ↔ one domain's adapter — never a runtime decision made anywhere in Go code.

Documentation

Overview

Package githubactions provides the HTTP client and GitHub Actions-specific facts (run status/conclusion vocabulary and run id encoding) shared by every domain's GitHub Actions-backed BuildRunner. It intentionally holds no BuildRunner interface or domain entity types — each domain (submitqueue, stovepipe, ...) defines its own BuildRunner and its own BuildStatus, and adapts this package's RunStatus to it. See platform/buildkite's README for the analogous rationale applied to the Buildkite backend.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.New("githubactions: resource not found")

ErrNotFound is returned when the GitHub Actions API responds with 404 to a request for a resource by ID (e.g. GetRun on an unknown run, or CancelRun on an already-deleted run).

Functions

func EncodeRunID 

func EncodeRunID(runID int64) string

EncodeRunID encodes a GitHub Actions workflow run id as an opaque build id string.

func ParseRunID 

func ParseRunID(id string) (int64, error)

ParseRunID is the inverse of EncodeRunID.

func RunMetadata 

func RunMetadata(run WorkflowRun) map[string]string

RunMetadata builds the caller-facing metadata map for a workflow run: the run's own identity and outcome fields, keyed for direct use as (or merge into) a domain's BuildMetadata.

Types

type Client 

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

Client is a thin wrapper around the GitHub Actions REST endpoints a BuildRunner needs: workflow dispatch, get workflow run, and cancel run. It is bound to a single repository and workflow.

func NewClient 

func NewClient(httpClient *http.Client, owner, repo, workflowID string) *Client

NewClient wraps a pre-configured *http.Client as a GitHub Actions Client bound to one repository and workflow. The caller is responsible for base URL resolution (e.g. via platform/http.BaseURLTransport, typically "https://api.github.com") and auth (a token with actions:read/actions:write injected via a transport).

func (*Client) CancelRun 

func (c *Client) CancelRun(ctx context.Context, runID int64) error

CancelRun requests cancellation of the workflow run. Returns nil when the run is already terminal or otherwise not cancellable (HTTP 409/422) — the BuildRunner contract treats that as a no-op.

func (*Client) DispatchWorkflow 

func (c *Client) DispatchWorkflow(ctx context.Context, req DispatchWorkflowRequest) (DispatchWorkflowResponse, error)

DispatchWorkflow dispatches the bound workflow.

Dispatching is not idempotent and a rejection carries its status code like any other, so a caller that retries a 502 can start a second run when the first was already accepted. Callers that cannot tolerate that need their own idempotency check.

func (*Client) GetRun 

func (c *Client) GetRun(ctx context.Context, runID int64) (WorkflowRun, error)

GetRun fetches a workflow run by its GitHub run id.

func (*Client) Owner 

func (c *Client) Owner() string

Owner is the repository owner or organization this Client is bound to.

func (*Client) Repo 

func (c *Client) Repo() string

Repo is the repository name this Client is bound to.

func (*Client) WorkflowID 

func (c *Client) WorkflowID() string

WorkflowID is the workflow file name or numeric workflow ID this Client is bound to.

type DispatchWorkflowRequest 

type DispatchWorkflowRequest struct {
	Ref              string            `json:"ref"`
	ReturnRunDetails bool              `json:"return_run_details,omitempty"`
	Inputs           map[string]string `json:"inputs,omitempty"`
}

DispatchWorkflowRequest is the payload for POST .../dispatches.

type DispatchWorkflowResponse 

type DispatchWorkflowResponse struct {
	WorkflowRunID int64  `json:"workflow_run_id"`
	RunURL        string `json:"run_url"`
	HTMLURL       string `json:"html_url"`
}

DispatchWorkflowResponse is the subset of fields callers need from a dispatch-workflow response.

type RunStatus 

type RunStatus string

RunStatus is GitHub Actions' own run status/conclusion vocabulary, collapsed into the five states every domain's BuildStatus already distinguishes. 

const (
	// RunStatusUnknown is returned for a raw status/conclusion pair this
	// package does not recognize. Not terminal — callers should keep polling
	// rather than treat it as a final outcome.
	RunStatusUnknown RunStatus = ""
	// RunStatusAccepted means the run has been accepted for execution but has
	// not started yet (GitHub: queued, requested, waiting, pending).
	RunStatusAccepted RunStatus = "accepted"
	// RunStatusRunning means the run is currently executing (GitHub:
	// in_progress).
	RunStatusRunning RunStatus = "running"
	// RunStatusSucceeded means the run completed successfully (GitHub:
	// completed with conclusion success).
	RunStatusSucceeded RunStatus = "succeeded"
	// RunStatusFailed means the run completed without a passing result
	// (GitHub: completed with any conclusion other than success/cancelled).
	RunStatusFailed RunStatus = "failed"
	// RunStatusCancelled means the run was cancelled (GitHub: completed with
	// conclusion cancelled).
	RunStatusCancelled RunStatus = "cancelled"
)

func ParseRunStatus 

func ParseRunStatus(status, conclusion string) RunStatus

ParseRunStatus maps a raw GitHub Actions run status/conclusion pair to a RunStatus. conclusion is only consulted when status is "completed". An unrecognized status, or a completed run with an empty conclusion, maps to RunStatusUnknown rather than being assumed terminal.

type WorkflowRun 

type WorkflowRun struct {
	ID           int64  `json:"id"`
	Name         string `json:"name"`
	DisplayTitle string `json:"display_title"`
	Status       string `json:"status"`
	Conclusion   string `json:"conclusion"`
	HTMLURL      string `json:"html_url"`
	RunAttempt   int    `json:"run_attempt"`
	Event        string `json:"event"`
	HeadBranch   string `json:"head_branch"`
	CreatedAt    string `json:"created_at"`
}

WorkflowRun is the subset of a GitHub Actions workflow run object callers need.

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.