github

Documentation

Index

• type Client
  • func NewClient(token, owner, repo string) *Client
  • func NewClientFromEnv() (*Client, error)
  • func NewClientWithBaseURL(token, owner, repo, baseURL string) (*Client, error)
  • func (c *Client) CreatePullRequest(ctx context.Context, title, body, head, base string, draft bool) (int, string, error)
  • func (c *Client) DeleteAllArtifacts(ctx context.Context) (deleted int, freedBytes int64, err error)
  • func (c *Client) DeleteArtifact(ctx context.Context, artifactID int64) error
  • func (c *Client) DeleteArtifactsBefore(ctx context.Context, before time.Time) (deleted int, freedBytes int64, err error)
  • func (c *Client) DeleteExpiredArtifacts(ctx context.Context) (deleted int, freedBytes int64, err error)
  • func (c *Client) DownloadArtifact(ctx context.Context, artifactID int64) (io.ReadCloser, error)
  • func (c *Client) GetLatestRunForBranch(ctx context.Context, branch string) (*remote.Workflow, error)
  • func (c *Client) GetLatestRunForTag(ctx context.Context, tag string) (*remote.Workflow, error)
  • func (c *Client) GetLatestWorkflow(ctx context.Context, branch string) (*remote.Workflow, error)
  • func (c *Client) GetPullRequest(ctx context.Context, prNumber int) (*github.PullRequest, error)
  • func (c *Client) GetPullRequestByBranch(ctx context.Context, branch string) (int, string, error)
  • func (c *Client) GetPullRequestChecks(ctx context.Context, prNumber int) (*remote.PRChecks, error)
  • func (c *Client) GetPullRequestDetails(ctx context.Context, prNumber int) (*remote.PullRequestDetails, error)
  • func (c *Client) GetPullRequestReviews(ctx context.Context, prNumber int) ([]*github.PullRequestReview, error)
  • func (c *Client) GetPullRequestTitle(ctx context.Context, prNumber int) (string, error)
  • func (c *Client) GetWorkflowRun(ctx context.Context, runID string) (*remote.Workflow, error)
  • func (c *Client) ListArtifacts(ctx context.Context) (*remote.ArtifactStats, error)
  • func (c *Client) ListPullRequests(ctx context.Context, state string) ([]*github.PullRequest, error)
  • func (c *Client) ListRunArtifacts(ctx context.Context, runID string) ([]remote.Artifact, error)
  • func (c *Client) ListRuns(ctx context.Context, workflowFile, branch string, limit int) ([]remote.Workflow, error)
  • func (c *Client) MarkPullRequestReady(ctx context.Context, prNumber int) error
  • func (c *Client) MergePullRequest(ctx context.Context, prNumber int, method string) error
  • func (c *Client) RerunWorkflow(ctx context.Context, runID string, failedOnly bool) error
  • func (c *Client) TriggerWorkflow(ctx context.Context, workflowFile, ref string, inputs map[string]string) (*remote.Workflow, error)
  • func (c *Client) UpdatePullRequest(ctx context.Context, prNumber int, title, body string) error
  • func (c *Client) WaitForChecksToStart(ctx context.Context, prNumber int, expectedSHA string, timeout time.Duration) (string, *remote.PRChecks, error)
  • func (c *Client) WatchPullRequestChecks(ctx context.Context, prNumber int) (<-chan remote.PRChecksUpdate, error)
  • func (c *Client) WatchWorkflow(ctx context.Context, workflowID string) (<-chan remote.WorkflowUpdate, error)

Types

type Client

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

Client implements remote.Provider for GitHub Actions

func NewClient

func NewClient(token, owner, repo string) *Client

NewClient creates a new GitHub client with token authentication

func NewClientFromEnv

func NewClientFromEnv() (*Client, error)

NewClientFromEnv creates a GitHub client using environment variables and git remote

func NewClientWithBaseURL

func NewClientWithBaseURL(token, owner, repo, baseURL string) (*Client, error)

NewClientWithBaseURL creates a new GitHub client for GitHub Enterprise with custom base URL

func (*Client) CreatePullRequest

func (c *Client) CreatePullRequest(ctx context.Context, title, body, head, base string, draft bool) (int, string, error)

CreatePullRequest creates a new pull request

func (*Client) DeleteAllArtifacts

func (c *Client) DeleteAllArtifacts(ctx context.Context) (deleted int, freedBytes int64, err error)

DeleteAllArtifacts deletes all artifacts in the repository

func (*Client) DeleteArtifact

func (c *Client) DeleteArtifact(ctx context.Context, artifactID int64) error

DeleteArtifact deletes a single artifact by ID

func (*Client) DeleteArtifactsBefore

func (c *Client) DeleteArtifactsBefore(ctx context.Context, before time.Time) (deleted int, freedBytes int64, err error)

DeleteArtifactsBefore deletes all artifacts created before the given time

func (*Client) DeleteExpiredArtifacts

func (c *Client) DeleteExpiredArtifacts(ctx context.Context) (deleted int, freedBytes int64, err error)

DeleteExpiredArtifacts deletes all expired artifacts

func (*Client) DownloadArtifact

func (c *Client) DownloadArtifact(ctx context.Context, artifactID int64) (io.ReadCloser, error)

DownloadArtifact opens the zip archive of one artifact.

GitHub answers the artifact endpoint with a 302 to a pre-signed blob URL that carries its own credentials, so the second request is a plain GET: sending the token there would hand it to a storage host that never asked for it.

func (*Client) GetLatestRunForBranch

func (c *Client) GetLatestRunForBranch(ctx context.Context, branch string) (*remote.Workflow, error)

GetLatestRunForBranch returns the most recent workflow run on a branch across all workflows in the repository. Unlike GetLatestWorkflow, it is not scoped to a specific workflow filename, so it works for repositories that don't use cidx-generated workflows. Used by `cidx workflow watch` to support watching runs on non-PR branches (issue #125).

func (*Client) GetLatestRunForTag

func (c *Client) GetLatestRunForTag(ctx context.Context, tag string) (*remote.Workflow, error)

GetLatestRunForTag returns the most recent workflow run triggered by the push of a tag. GitHub records the ref that started a run in head_branch -- for a tag push that is the tag name -- and the repository-wide runs listing filters on it. Resolving by ref instead of by workflow file name means the release workflow is found whatever it is called, and the runs that a branch push of the very same commit produced (CI, nightly) are left out because their ref is the branch, not the tag (issue #223).

func (*Client) GetLatestWorkflow

func (c *Client) GetLatestWorkflow(ctx context.Context, branch string) (*remote.Workflow, error)

GetLatestWorkflow returns the most recent workflow run for a branch. The workflow filename is not hardcoded: the candidate names from remote.CandidateWorkflowFiles are probed in preference order, so both generated projects (cidx.yml) and repos with a conventional ci.yml work without configuration (issue #170).

func (*Client) GetPullRequest

func (c *Client) GetPullRequest(ctx context.Context, prNumber int) (*github.PullRequest, error)

GetPullRequest returns a single pull request by number

func (*Client) GetPullRequestByBranch

func (c *Client) GetPullRequestByBranch(ctx context.Context, branch string) (int, string, error)

GetPullRequestByBranch finds a PR for the given head branch

func (*Client) GetPullRequestChecks

func (c *Client) GetPullRequestChecks(ctx context.Context, prNumber int) (*remote.PRChecks, error)

GetPullRequestChecks returns the status of all checks/workflows for a PR

func (*Client) GetPullRequestDetails

func (c *Client) GetPullRequestDetails(ctx context.Context, prNumber int) (*remote.PullRequestDetails, error)

GetPullRequestDetails returns comprehensive PR details for TUI display

func (*Client) GetPullRequestReviews

func (c *Client) GetPullRequestReviews(ctx context.Context, prNumber int) ([]*github.PullRequestReview, error)

GetPullRequestReviews returns reviews for a pull request

func (*Client) GetPullRequestTitle

func (c *Client) GetPullRequestTitle(ctx context.Context, prNumber int) (string, error)

GetPullRequestTitle returns the title of a pull request.

func (*Client) GetWorkflowRun

func (c *Client) GetWorkflowRun(ctx context.Context, runID string) (*remote.Workflow, error)

GetWorkflowRun returns a workflow run by its ID. Used by `cidx workflow watch --run <id>` to watch a specific run.

func (*Client) ListArtifacts

func (c *Client) ListArtifacts(ctx context.Context) (*remote.ArtifactStats, error)

ListArtifacts returns all artifacts for the repository with storage statistics

func (*Client) ListPullRequests

func (c *Client) ListPullRequests(ctx context.Context, state string) ([]*github.PullRequest, error)

ListPullRequests lists pull requests with the given state (open, closed, all)

func (*Client) ListRunArtifacts

func (c *Client) ListRunArtifacts(ctx context.Context, runID string) ([]remote.Artifact, error)

ListRunArtifacts returns the artifacts one run produced.

The repository-wide ListArtifacts above cannot answer this: the audit uploads one artifact per matrix leg, so "the trivy results" is a set of twelve that only means anything taken from the same run (issue #285).

func (*Client) ListRuns

func (c *Client) ListRuns(ctx context.Context, workflowFile, branch string, limit int) ([]remote.Workflow, error)

ListRuns returns the most recent runs, newest first.

With no workflow file it reads the repository-wide listing, which is the answer to "what ran on this branch": a check that has just failed names a job, not the workflow file that carries it, and having to guess the file before being allowed to look is what sent this question to `gh` (issue #342).

A workflow file the repository does not have is not an error -- the caller gets an empty listing and says so, the same way the gh-backed version did.

func (*Client) MarkPullRequestReady

func (c *Client) MarkPullRequestReady(ctx context.Context, prNumber int) error

MarkPullRequestReady marks a draft PR as ready for review

func (*Client) MergePullRequest

func (c *Client) MergePullRequest(ctx context.Context, prNumber int, method string) error

MergePullRequest merges a pull request

func (*Client) RerunWorkflow

func (c *Client) RerunWorkflow(ctx context.Context, runID string, failedOnly bool) error

RerunWorkflow restarts a run, or only the jobs of it that failed.

Both endpoints answer 201 with no body and start a *new attempt of the same run*, so the run ID stays valid and the caller can watch it straight away -- which is the whole point of having this next to `workflow watch` (issue #342).

func (*Client) TriggerWorkflow

func (c *Client) TriggerWorkflow(ctx context.Context, workflowFile, ref string, inputs map[string]string) (*remote.Workflow, error)

TriggerWorkflow dispatches workflowFile on ref and returns the run it created.

The API this builds on (POST .../workflows/{file}/dispatches) answers 204 with an empty body: it does not say which run it created. The run is therefore identified afterwards, and the identification is deliberately conservative (issue #266):

• the runs of that workflow, on that ref, with event workflow_dispatch are listed *before* the dispatch, and every one of them is excluded;
• candidates older than that listing are excluded too, which is what keeps the filter meaningful if the listing itself failed. The cutoff is the server's own clock, read from that response's Date header: GitHub creates the run before it answers the dispatch, so anchoring on the dispatch's own Date would rule out the very run we are looking for;
• candidates triggered by another account are excluded, when the authenticated login can be resolved;
• of what survives, the oldest is taken: a dispatch made after ours can only have produced a newer run.

What that guarantees: the returned run is never one that already existed, never belongs to another workflow, ref or trigger, and never belongs to another user. What it cannot guarantee: if the same account dispatches the same workflow on the same ref at the same moment, the two runs are indistinguishable through this API and the wrong one may be returned.

func (*Client) UpdatePullRequest

func (c *Client) UpdatePullRequest(ctx context.Context, prNumber int, title, body string) error

UpdatePullRequest updates the title and/or body of a pull request. Empty strings leave the corresponding field unchanged.

func (*Client) WaitForChecksToStart

func (c *Client) WaitForChecksToStart(ctx context.Context, prNumber int, expectedSHA string, timeout time.Duration) (string, *remote.PRChecks, error)

WaitForChecksToStart waits for CI checks to start for a PR This solves the race condition where CI hasn't started yet when we query

func (*Client) WatchPullRequestChecks

func (c *Client) WatchPullRequestChecks(ctx context.Context, prNumber int) (<-chan remote.PRChecksUpdate, error)

WatchPullRequestChecks streams updates for PR checks until all complete

func (*Client) WatchWorkflow

func (c *Client) WatchWorkflow(ctx context.Context, workflowID string) (<-chan remote.WorkflowUpdate, error)

WatchWorkflow streams updates for a running workflow