github

package
v0.51.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package github implements forge.Client for the GitHub REST API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultAgentRoles

func DefaultAgentRoles() []string

DefaultAgentRoles returns the standard set of agent roles.

func IsPATForbiddenError added in v0.30.0

func IsPATForbiddenError(err error) bool

IsPATForbiddenError reports whether err is a GitHub 403 indicating that the org forbids classic personal access tokens. This specific message means the caller needs a fine-grained PAT, GitHub App, or OAuth App token instead.

func IsRateLimitError added in v0.27.0

func IsRateLimitError(err error) bool

IsRateLimitError reports whether err is a GitHub rate-limit error (primary 429, primary-as-403, or secondary 403). It unwraps the error chain, so wrapped errors are detected too.

func ListInstallationRepositories added in v0.24.0

func ListInstallationRepositories(ctx context.Context, httpClient *http.Client, baseURL, token string, perPage int) (repos []string, totalCount int, ok bool, err error)

ListInstallationRepositories returns repository full names when token is a GitHub App installation token (HTTP 200). PATs and OAuth tokens that lack installation access receive 401/403 and return (nil, 0, false, nil).

func ProbeInstallationToken added in v0.24.0

func ProbeInstallationToken(ctx context.Context, httpClient *http.Client, baseURL, token string) (bool, error)

ProbeInstallationToken reports whether token is a GitHub App installation access token by calling GET /installation/repositories. PATs and OAuth tokens receive 401/403 on that endpoint.

func RetryAfterFromError added in v0.49.0

func RetryAfterFromError(err error) (d time.Duration, ok bool)

RetryAfterFromError returns the Retry-After wait carried by an APIError in err's chain. ok is false when err carries none.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
	Errors     []APIErrorDetail
	// RetryAfter is the wait the final response's Retry-After header
	// asked for, uncapped. Zero when the header was absent or not a
	// positive number of seconds.
	RetryAfter time.Duration
	// contains filtered or unexported fields
}

APIError represents an error response from the GitHub API.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) IsTransient added in v0.37.0

func (e *APIError) IsTransient() bool

IsTransient reports whether the API error represents a transient failure that may succeed on retry: server errors (500–504) and rate limits (429). An error whose rate-limit backoff was cut short by the caller's context (cause set) is not transient: retrying after the context was cancelled or its deadline passed would defy caller intent. This method satisfies the transientReporter interface used by forge.IsTransient.

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

Unwrap returns sentinel errors for well-known API responses.

ErrBranchProtected is intentionally NOT mapped here. Branch protection 422s are context-dependent: the word "protected" in a validation error only signals a branch-protection failure when it comes from a ref update (PATCH /git/refs). Other 422s may coincidentally mention "protected" in unrelated contexts. The wrapping happens in commitFilesTo where the operation context is known.

ErrForbidden is intentionally NOT mapped here either. HTTP 403 can indicate secondary rate limits (handled by isRetryable), SAML SSO enforcement, or other policy-based denials — not only permission failures. The wrapping happens at call sites (e.g., CreateBranch) where the operation context disambiguates the cause.

type APIErrorDetail added in v0.8.0

type APIErrorDetail struct {
	Resource string `json:"resource"`
	Field    string `json:"field"`
	Code     string `json:"code"`
	Message  string `json:"message"`
}

APIErrorDetail is one validation error entry returned by GitHub.

type AppConfig

type AppConfig struct {
	Name           string         `json:"name"`
	Description    string         `json:"description"`
	URL            string         `json:"url"`
	HookAttributes HookAttributes `json:"hook_attributes"`
	RedirectURL    string         `json:"redirect_url,omitempty"`
	Public         bool           `json:"public"`
	Permissions    AppPermissions `json:"default_permissions"`
	Events         []string       `json:"default_events"`
}

AppConfig defines the configuration for creating a GitHub App via the manifest flow. See https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest

func AgentAppConfig

func AgentAppConfig(org, role, appSet string) AppConfig

AgentAppConfig returns the GitHub App configuration for a given agent role.

Important: GitHub validates that event subscriptions are backed by matching permissions. For example, subscribing to "issues" events requires at least issues:read permission. Subscribing to "issue_comment" requires issues:read or issues:write. Mismatches cause the manifest to be rejected. Every Events entry below must have a corresponding permission.

type AppPermissions

type AppPermissions struct {
	Actions                    string `json:"actions,omitempty"`
	Issues                     string `json:"issues,omitempty"`
	PullRequests               string `json:"pull_requests,omitempty"`
	Checks                     string `json:"checks,omitempty"`
	Contents                   string `json:"contents,omitempty"`
	Variables                  string `json:"actions_variables,omitempty"`
	Workflows                  string `json:"workflows,omitempty"`
	Administration             string `json:"administration,omitempty"`
	Members                    string `json:"members,omitempty"`
	OrganizationProjects       string `json:"organization_projects,omitempty"`
	OrganizationAdministration string `json:"organization_administration,omitempty"`
	// OrganizationActionsVariables is org-level Actions variables (distinct from
	// repository actions_variables). Required to read FULLSEND_FOREIGN_* via the org API.
	OrganizationActionsVariables string `json:"organization_actions_variables,omitempty"`
	Packages                     string `json:"packages,omitempty"`
	Secrets                      string `json:"secrets,omitempty"`
}

AppPermissions defines the permissions for a GitHub App.

type HookAttributes

type HookAttributes struct {
	URL    string `json:"url"`
	Active bool   `json:"active"`
}

HookAttributes configures the webhook for a GitHub App. Even when webhooks are not used, GitHub requires this field in the manifest.

type LiveClient

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

LiveClient implements forge.Client for the GitHub REST API.

Rate-limit blocking: when GitHub answers 429 or 403 for an exhausted primary quota (X-RateLimit-Remaining 0, no Retry-After), a request waits for X-RateLimit-Reset, for at most maxPrimaryResetWait (65 minutes), instead of failing after the short backoff retries. A caller whose context has no deadline can therefore block for up to about an hour; set a context deadline to bound the wait. When the deadline cannot cover the wait, the request fails at once with a rate-limit error. When the context ends during a rate-limit wait, the error is a rate-limit *APIError whose Unwrap returns the context error, so errors.Is matches context.Canceled or context.DeadlineExceeded.

func New

func New(token string) *LiveClient

New creates a new GitHub client with the given personal access token.

func (*LiveClient) AddCollaborator added in v0.44.0

func (c *LiveClient) AddCollaborator(ctx context.Context, owner, repo, username, permission string) error

func (*LiveClient) AddIssueCommentReaction added in v0.38.0

func (c *LiveClient) AddIssueCommentReaction(ctx context.Context, owner, repo string, commentID int, content string) (int64, error)

AddIssueCommentReaction adds an emoji reaction to an issue/PR comment.

func (*LiveClient) AddIssueLabels added in v0.30.0

func (c *LiveClient) AddIssueLabels(ctx context.Context, owner, repo string, number int, labels ...string) error

AddIssueLabels adds labels to an existing issue.

func (*LiveClient) AddIssueReaction added in v0.38.0

func (c *LiveClient) AddIssueReaction(ctx context.Context, owner, repo string, number int, content string) (int64, error)

AddIssueReaction adds an emoji reaction to an issue or pull request.

func (*LiveClient) BaseURL added in v0.40.0

func (c *LiveClient) BaseURL() string

BaseURL returns the configured GitHub API base URL.

func (*LiveClient) CloseChangeProposal added in v0.33.0

func (c *LiveClient) CloseChangeProposal(ctx context.Context, owner, repo string, number int) error

CloseChangeProposal closes an open pull request without merging it.

func (*LiveClient) CloseIssue added in v0.0.3

func (c *LiveClient) CloseIssue(ctx context.Context, owner, repo string, number int) error

CloseIssue closes an issue by number.

func (*LiveClient) CommitFiles added in v0.6.0

func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message string, files []forge.TreeFile) (bool, error)

CommitFiles atomically commits multiple files to the default branch. Returns (false, nil) when all files already match the current tree.

Regular inline files are committed with createCommitOnBranch, which GitHub signs (see commit_graphql.go). Anything else uses the Git Trees/Blobs/Commits API: text as inline tree content, binaries via the Blob API, TreeFile.LocalPath hashed and streamed from disk.

Returns forge.ErrBranchProtected when a rule rejects the commit, also wrapping forge.ErrSignedCommitsRequired for a signature rule.

func (*LiveClient) CommitFilesToBranch added in v0.18.0

func (c *LiveClient) CommitFilesToBranch(ctx context.Context, owner, repo, branch, message string, files []forge.TreeFile) (bool, error)

CommitFilesToBranch atomically commits multiple files to a specific branch. Like CommitFiles, it is idempotent.

func (*LiveClient) CompareCommits added in v0.37.0

func (c *LiveClient) CompareCommits(ctx context.Context, owner, repo, base, head string) (string, error)

CompareCommits compares two commits and returns their relationship status: "ahead" (head is ahead of base), "behind", "identical", or "diverged".

func (*LiveClient) CreateBranch

func (c *LiveClient) CreateBranch(ctx context.Context, owner, repo, branchName string) error

CreateBranch creates a new branch from the repository's default branch.

func (*LiveClient) CreateBranchFromSHA added in v0.34.0

func (c *LiveClient) CreateBranchFromSHA(ctx context.Context, owner, repo, branchName, sha string) error

CreateBranchFromSHA creates a new branch pointing at the given commit SHA. Unlike CreateBranch (which resolves the repo's default branch), this allows the caller to specify an explicit starting point. Returns forge.ErrForbidden on insufficient permissions.

func (*LiveClient) CreateChangeProposal

func (c *LiveClient) CreateChangeProposal(ctx context.Context, owner, repo, title, body, head, base string) (*forge.ChangeProposal, error)

CreateChangeProposal creates a pull request. Returns forge.ErrForbidden (wrapped) on insufficient permissions.

func (*LiveClient) CreateCrossRepoChangeProposal added in v0.33.0

func (c *LiveClient) CreateCrossRepoChangeProposal(ctx context.Context, baseOwner, baseRepo, headOwner, headRepo, title, body, headBranch, baseBranch string) (*forge.ChangeProposal, error)

CreateCrossRepoChangeProposal opens a pull request where the head branch lives in a different repository than the base. It uses the GraphQL createPullRequest mutation with explicit repositoryId and headRepositoryId to avoid the ambiguity of the REST API's "owner:branch" head format (which fails for same-owner forks).

func (*LiveClient) CreateFile

func (c *LiveClient) CreateFile(ctx context.Context, owner, repo, path, message string, content []byte) error

CreateFile creates a new file on the repository's default branch.

func (*LiveClient) CreateFileOnBranch

func (c *LiveClient) CreateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

CreateFileOnBranch creates a file on a specific branch (or default if empty).

Retries on 404 to handle GitHub's async repo initialization: after CreateRepo with auto_init, the default branch may not be materialized yet and the Contents API returns 404. Also retries on 409 (conflict) which can occur when the branch ref is being updated by a concurrent write.

GitHub quirk: writing to .github/workflows/ paths returns 404 (not 403) when the token lacks the "workflow" scope. If you hit persistent 404s on workflow file creation, the fix is: gh auth refresh -s workflow

func (*LiveClient) CreateFork added in v0.24.0

func (c *LiveClient) CreateFork(ctx context.Context, owner, repo string) (string, string, error)

CreateFork creates a fork of owner/repo under the authenticated user's account. If a fork already exists, the GitHub API returns 202 with the existing fork metadata, so this call is idempotent. Returns both the fork owner login and the actual repo name. The repo name may differ from the upstream when the user already has an unrelated repo with the same name (GitHub appends a suffix like "-1").

func (*LiveClient) CreateForkInOrg added in v0.32.0

func (c *LiveClient) CreateForkInOrg(ctx context.Context, owner, repo, org, forkName string) (string, error)

CreateForkInOrg creates a fork of owner/repo under the specified organization with the given name. If a fork of the source already exists with the given name, the GitHub API returns 202 with the existing fork metadata, so this call is idempotent. Returns the actual repo name from the API response.

If a repository with the target name already exists but is not a fork of the source, returns forge.ErrNotFork. This pre-check prevents a generic GitHub 422 error with a specific sentinel so callers can handle the collision gracefully.

func (*LiveClient) CreateIssue added in v0.0.3

func (c *LiveClient) CreateIssue(ctx context.Context, owner, repo, title, body string, labels ...string) (*forge.Issue, error)

CreateIssue creates a new issue on a repository. Labels are best-effort: if GitHub rejects the create because a label is unavailable in the target repo, the request is retried without labels so issue creation still succeeds.

func (*LiveClient) CreateIssueComment added in v0.2.0

func (c *LiveClient) CreateIssueComment(ctx context.Context, owner, repo string, number int, body string) (*forge.IssueComment, error)

CreateIssueComment creates a new comment on an issue or pull request.

func (*LiveClient) CreateOrUpdateFile

func (c *LiveClient) CreateOrUpdateFile(ctx context.Context, owner, repo, path, message string, content []byte) error

CreateOrUpdateFile creates a file or updates it if it already exists. Retries on 404/409 to handle async repo initialization and branch ref races.

func (*LiveClient) CreateOrUpdateFileOnBranch

func (c *LiveClient) CreateOrUpdateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

CreateOrUpdateFileOnBranch creates or updates a file on a specific branch. Like CreateOrUpdateFile, it fetches the existing SHA before updating. Retries on 404/409 for async repo init and branch ref races.

func (*LiveClient) CreateOrUpdateOrgVariableAll added in v0.24.0

func (c *LiveClient) CreateOrUpdateOrgVariableAll(ctx context.Context, org, name, value string) error

CreateOrUpdateOrgVariableAll creates or updates an org-level Actions variable visible to all repositories in the org (visibility all).

func (*LiveClient) CreateOrUpdateRepoVariable

func (c *LiveClient) CreateOrUpdateRepoVariable(ctx context.Context, owner, repo, name, value string) error

CreateOrUpdateRepoVariable creates or updates a repository Actions variable.

func (*LiveClient) CreatePipeline added in v0.33.0

func (c *LiveClient) CreatePipeline(_ context.Context, _, _, _ string, _ map[string]string) (*forge.Pipeline, error)

CreatePipeline is not supported on GitHub.

func (*LiveClient) CreatePipelineSchedule added in v0.31.0

func (c *LiveClient) CreatePipelineSchedule(_ context.Context, owner, repo, ref, description, cron string, _ map[string]string) (int64, error)

CreatePipelineSchedule is not supported on GitHub.

func (*LiveClient) CreatePipelineScheduleWithActive added in v0.49.0

func (c *LiveClient) CreatePipelineScheduleWithActive(_ context.Context, owner, repo, ref, description, cron string, _ map[string]string, _ bool) (int64, error)

CreatePipelineScheduleWithActive is not supported on GitHub.

func (*LiveClient) CreatePipelineTriggerToken added in v0.44.0

func (c *LiveClient) CreatePipelineTriggerToken(_ context.Context, _, _, _ string) (*forge.PipelineTriggerToken, error)

CreatePipelineTriggerToken is not supported on GitHub.

func (*LiveClient) CreatePipelineWithInputs added in v0.44.0

func (c *LiveClient) CreatePipelineWithInputs(_ context.Context, _, _, _ string, _ map[string]forge.PipelineInputValue) (*forge.Pipeline, error)

CreatePipelineWithInputs is not supported on GitHub. GitHub Actions has no equivalent to GitLab CI/CD Inputs for API-triggered workflow runs.

func (*LiveClient) CreateProjectHook added in v0.44.0

func (c *LiveClient) CreateProjectHook(_ context.Context, _, _ string, _ forge.ProjectHook) (*forge.ProjectHook, error)

CreateProjectHook is not supported on GitHub.

func (*LiveClient) CreateProtectedCIVariable added in v0.31.0

func (c *LiveClient) CreateProtectedCIVariable(_ context.Context, _, _, _, _ string) error

CreateProtectedCIVariable is not supported on GitHub.

func (*LiveClient) CreatePullRequestReview added in v0.2.0

func (c *LiveClient) CreatePullRequestReview(ctx context.Context, owner, repo string, number int, event, body, commitSHA string, comments []forge.ReviewComment) error

CreatePullRequestReview submits a formal review on a pull request. The event must be one of: APPROVE, REQUEST_CHANGES, COMMENT. When commitSHA is non-empty it is sent as commit_id, pinning the review to that commit. GitHub rejects the request if the commit is not the PR's current HEAD, closing the TOCTOU gap between the stale-head check and review submission. When comments is non-nil, inline diff comments are attached to the review via the GitHub "comments" field.

func (*LiveClient) CreateRepo

func (c *LiveClient) CreateRepo(ctx context.Context, org, name, description string, private bool) (*forge.Repository, error)

CreateRepo creates a new repository under an organization.

The repo is created with auto_init: true so that a default branch exists immediately. However, GitHub's auto_init is asynchronous — the API returns 201 before the initial commit is fully materialized. Callers writing files to the new repo via the Contents API should expect transient 404s and retry with backoff. See the retry logic in LiveClient.do().

func (*LiveClient) CreateRepoSecret

func (c *LiveClient) CreateRepoSecret(ctx context.Context, owner, repo, name, value string) error

CreateRepoSecret creates or updates an encrypted repository secret.

func (*LiveClient) DeleteBranch added in v0.44.0

func (c *LiveClient) DeleteBranch(ctx context.Context, owner, repo, branchName string) error

DeleteBranch deletes a git branch. Returns forge.ErrNotFound (wrapped) if the branch does not exist.

func (*LiveClient) DeleteFile added in v0.1.0

func (c *LiveClient) DeleteFile(ctx context.Context, owner, repo, path, message string) error

DeleteFile deletes a file from the repository's default branch. It first fetches the file to obtain its SHA (required by the GitHub Contents API), then issues the DELETE. Retries on transient 404/409 errors.

func (*LiveClient) DeleteFiles added in v0.19.0

func (c *LiveClient) DeleteFiles(ctx context.Context, owner, repo, message string, paths []string) (int, error)

DeleteFiles atomically removes paths from the repository default branch with a createCommitOnBranch commit, retried like CommitFiles.

func (*LiveClient) DeleteIssueComment added in v0.15.0

func (c *LiveClient) DeleteIssueComment(ctx context.Context, owner, repo string, commentID int) error

DeleteIssueComment deletes an issue comment by its numeric ID.

func (*LiveClient) DeleteIssueCommentReaction added in v0.38.0

func (c *LiveClient) DeleteIssueCommentReaction(ctx context.Context, owner, repo string, commentID int, reactionID int64) error

DeleteIssueCommentReaction removes a previously added comment reaction by ID.

func (*LiveClient) DeleteIssueReaction added in v0.38.0

func (c *LiveClient) DeleteIssueReaction(ctx context.Context, owner, repo string, number int, reactionID int64) error

DeleteIssueReaction removes a previously added reaction by ID.

func (*LiveClient) DeleteOrgSecret

func (c *LiveClient) DeleteOrgSecret(ctx context.Context, org, name string) error

DeleteOrgSecret deletes an org-level secret. It is idempotent: a 404 (secret already gone) is not treated as an error.

func (*LiveClient) DeleteOrgVariable added in v0.8.0

func (c *LiveClient) DeleteOrgVariable(ctx context.Context, org, name string) error

DeleteOrgVariable deletes an org-level variable. It is idempotent: a 404 (variable already gone) is not treated as an error.

func (*LiveClient) DeletePipelineSchedule added in v0.31.0

func (c *LiveClient) DeletePipelineSchedule(_ context.Context, owner, repo string, scheduleID int64) error

DeletePipelineSchedule is not supported on GitHub.

func (*LiveClient) DeleteProjectHook added in v0.44.0

func (c *LiveClient) DeleteProjectHook(_ context.Context, _, _ string, _ int64) error

DeleteProjectHook is not supported on GitHub.

func (*LiveClient) DeleteProjectServiceAccount added in v0.46.0

func (c *LiveClient) DeleteProjectServiceAccount(_ context.Context, _, _ string, _ int) error

DeleteProjectServiceAccount is not supported on GitHub.

func (*LiveClient) DeleteRef added in v0.33.0

func (c *LiveClient) DeleteRef(ctx context.Context, owner, repo, refPath string) error

DeleteRef deletes a git ref (e.g., "heads/my-branch", "tags/v1.0"). Returns forge.ErrNotFound (wrapped) if the ref does not exist. GitHub reports a missing ref on delete as 422 "Reference does not exist" rather than 404, so that response is mapped to forge.ErrNotFound here; the generic APIError.Unwrap 422 handling is deliberately left unchanged.

func (*LiveClient) DeleteRepo

func (c *LiveClient) DeleteRepo(ctx context.Context, owner, repo string) error

DeleteRepo deletes a repository.

func (*LiveClient) DeleteRepoSecret added in v0.28.0

func (c *LiveClient) DeleteRepoSecret(ctx context.Context, owner, repo, name string) error

DeleteRepoSecret deletes a repository Actions secret. It is idempotent: a 404 (secret already gone) is not treated as an error.

func (*LiveClient) DeleteRepoVariable added in v0.28.0

func (c *LiveClient) DeleteRepoVariable(ctx context.Context, owner, repo, name string) error

DeleteRepoVariable deletes a repository Actions variable. It is idempotent: a 404 (variable already gone) is not treated as an error.

func (*LiveClient) DismissPullRequestReview added in v0.6.0

func (c *LiveClient) DismissPullRequestReview(ctx context.Context, owner, repo string, number, reviewID int, message string) error

DismissPullRequestReview dismisses a review, changing its state to DISMISSED.

func (*LiveClient) DispatchWorkflow

func (c *LiveClient) DispatchWorkflow(ctx context.Context, owner, repo, workflowFile, ref string, inputs map[string]string) error

DispatchWorkflow triggers a workflow_dispatch event on a workflow file. GitHub returns 204 No Content on success (not 200 or 201).

func (*LiveClient) DownloadWorkflowRunArtifact added in v0.30.0

func (c *LiveClient) DownloadWorkflowRunArtifact(ctx context.Context, owner, repo string, artifactID int) ([]byte, error)

DownloadWorkflowRunArtifact returns the zip archive for a workflow artifact.

func (*LiveClient) FindExistingFork added in v0.24.0

func (c *LiveClient) FindExistingFork(ctx context.Context, owner, repo string) (string, string, error)

FindExistingFork checks whether the authenticated user already owns a fork of owner/repo by fetching GET /repos/{user}/{repo} and verifying the parent relationship. Returns the fork owner login and repo name if found, or empty strings when no fork exists. The repo name may differ from the upstream name when GitHub renamed it to avoid collisions. Only real API errors are returned as err.

func (*LiveClient) ForceCommitFileToBranch added in v0.44.0

func (c *LiveClient) ForceCommitFileToBranch(_ context.Context, _, _, _, _, _ string, _ []byte) error

ForceCommitFileToBranch is not supported on GitHub.

func (*LiveClient) GetAppClientID added in v0.1.0

func (c *LiveClient) GetAppClientID(ctx context.Context, slug string) (string, error)

func (*LiveClient) GetAuthenticatedUser

func (c *LiveClient) GetAuthenticatedUser(ctx context.Context) (string, error)

GetAuthenticatedUser returns the login of the authenticated user.

For classic PATs and OAuth tokens the identity comes from GET /user. GitHub App JWTs fall back to GET /app and derive "{slug}[bot]". Installation access tokens cannot use either REST endpoint; those fall back to a GraphQL viewer query, which returns the bot login directly.

func (*LiveClient) GetAuthenticatedUserIdentity added in v0.19.0

func (c *LiveClient) GetAuthenticatedUserIdentity(ctx context.Context) (*forge.UserIdentity, error)

GetAuthenticatedUserIdentity returns the display name and email of the authenticated user by calling GET /user.

For classic PATs and OAuth tokens the endpoint returns the user's profile including name, email, and numeric ID. When name is empty, login is used as a fallback. When email is empty, the GitHub noreply address is constructed from the user's ID and login.

GitHub App installation tokens cannot call /user, so this method returns forge.ErrNotFound for those token types.

func (*LiveClient) GetBranchRef added in v0.25.0

func (c *LiveClient) GetBranchRef(ctx context.Context, owner, repo, branch string) (string, error)

GetBranchRef returns the HEAD commit SHA for the named branch.

func (*LiveClient) GetCollaboratorPermission added in v0.31.0

func (c *LiveClient) GetCollaboratorPermission(ctx context.Context, owner, repo, username string) (string, error)

func (*LiveClient) GetFileContent

func (c *LiveClient) GetFileContent(ctx context.Context, owner, repo, path string) ([]byte, error)

GetFileContent retrieves the content of a file from a repository.

func (*LiveClient) GetFileContentAtRef added in v0.17.0

func (c *LiveClient) GetFileContentAtRef(ctx context.Context, owner, repo, path, ref string) ([]byte, error)

GetFileContentAtRef retrieves the content of a file at a specific ref (commit SHA, branch, or tag). Unlike GetFileContent which reads from the default branch, this reads from the specified ref.

func (*LiveClient) GetIssue added in v0.30.0

func (c *LiveClient) GetIssue(ctx context.Context, owner, repo string, number int) (*forge.Issue, error)

GetIssue returns an issue by number.

func (*LiveClient) GetIssueComment added in v0.45.0

func (c *LiveClient) GetIssueComment(ctx context.Context, owner, repo string, commentID int) (*forge.IssueComment, error)

GetIssueComment fetches a single comment by its numeric ID. GitHub addresses comments globally (no issue number needed in the path). owner and repo are percent-escaped into the request path: callers are expected to pass validated identifiers, but escaping keeps a stray delimiter in either field from being interpreted as a path or query separator instead of literal owner/repo data. Returns forge.ErrNotFound (wrapped) if the comment does not exist.

func (*LiveClient) GetJobTokenRepositoryPushAllowed added in v0.48.0

func (c *LiveClient) GetJobTokenRepositoryPushAllowed(_ context.Context, _, _ string) (bool, error)

GetJobTokenRepositoryPushAllowed is not supported on GitHub.

func (*LiveClient) GetLatestWorkflowRun

func (c *LiveClient) GetLatestWorkflowRun(ctx context.Context, owner, repo, workflowFile string) (*forge.WorkflowRun, error)

GetLatestWorkflowRun returns the most recent workflow run for a workflow file.

func (*LiveClient) GetOrgMembership added in v0.44.0

func (c *LiveClient) GetOrgMembership(ctx context.Context, org, username string) (forge.OrgMembership, error)

func (*LiveClient) GetOrgPlan added in v0.8.0

func (c *LiveClient) GetOrgPlan(ctx context.Context, org string) (string, error)

GetOrgPlan returns the billing plan name for the org (e.g. "free", "team", "enterprise").

func (*LiveClient) GetOrgVariable added in v0.24.0

func (c *LiveClient) GetOrgVariable(ctx context.Context, org, name string) (string, bool, error)

GetOrgVariable reads an org-level Actions variable value.

func (*LiveClient) GetPipelineSchedule added in v0.46.0

func (c *LiveClient) GetPipelineSchedule(_ context.Context, _, _ string, _ int64) (*forge.PipelineSchedule, error)

GetPipelineSchedule is not supported on GitHub.

func (*LiveClient) GetPipelineVariablesMinimumOverrideRole added in v0.44.0

func (c *LiveClient) GetPipelineVariablesMinimumOverrideRole(_ context.Context, _, _ string) (string, error)

GetPipelineVariablesMinimumOverrideRole is not supported on GitHub.

func (*LiveClient) GetProjectMemberAccessLevel added in v0.46.0

func (c *LiveClient) GetProjectMemberAccessLevel(_ context.Context, _, _ string, _ int64) (int, error)

GetProjectMemberAccessLevel is not supported on GitHub.

func (*LiveClient) GetProtectedBranch added in v0.44.0

func (c *LiveClient) GetProtectedBranch(_ context.Context, _, _, _ string) (*forge.ProtectedBranchRule, error)

GetProtectedBranch is not supported on GitHub. GitHub Actions does not gate workflow dispatch on protected-branch merge/push access the way GitLab gates CreatePipeline.

func (*LiveClient) GetPullRequestHeadSHA added in v0.2.0

func (c *LiveClient) GetPullRequestHeadSHA(ctx context.Context, owner, repo string, number int) (string, error)

GetPullRequestHeadSHA returns the current HEAD commit SHA of a pull request.

func (*LiveClient) GetPullRequestInfo added in v0.31.0

func (c *LiveClient) GetPullRequestInfo(ctx context.Context, owner, repo string, number int) (*forge.PullRequestInfo, error)

GetPullRequestInfo returns branch/repo context for a pull request.

func (*LiveClient) GetPushRuleBranchNameRegex added in v0.49.0

func (c *LiveClient) GetPushRuleBranchNameRegex(_ context.Context, _, _ string) (string, error)

GetPushRuleBranchNameRegex is not supported on GitHub.

func (*LiveClient) GetRef added in v0.29.0

func (c *LiveClient) GetRef(ctx context.Context, owner, repo, refPath string) (string, error)

GetRef returns the commit SHA for the given ref path (e.g., "heads/main", "tags/v0").

func (*LiveClient) GetRepo

func (c *LiveClient) GetRepo(ctx context.Context, owner, repo string) (*forge.Repository, error)

GetRepo retrieves a single repository by owner and name. Returns forge.ErrNotFound (wrapped) if the repo does not exist.

func (*LiveClient) GetRepoSecretProtection added in v0.46.0

func (c *LiveClient) GetRepoSecretProtection(ctx context.Context, owner, repo, name string) (forge.SecretProtection, error)

GetRepoSecretProtection reports whether a repository Actions secret exists. GitHub encrypts secrets and masks them in logs, and they have no branch-protection scoping, so an existing secret reports both controls.

func (*LiveClient) GetRepoVariable added in v0.8.0

func (c *LiveClient) GetRepoVariable(ctx context.Context, owner, repo, name string) (string, bool, error)

GetRepoVariable returns the value of a repository Actions variable. Returns ("", false, nil) if the variable does not exist.

func (*LiveClient) GetRepoVariableInfo added in v0.46.0

func (c *LiveClient) GetRepoVariableInfo(ctx context.Context, owner, repo, name string) (forge.RepoVariable, bool, error)

GetRepoVariableInfo returns an Actions variable; GitHub variables are not file-type.

func (*LiveClient) GetTokenScopes

func (c *LiveClient) GetTokenScopes(ctx context.Context) ([]string, error)

GetTokenScopes returns the OAuth scopes granted to the current token by inspecting the X-OAuth-Scopes header from a lightweight API call.

GitHub only populates X-OAuth-Scopes for classic PATs and OAuth tokens. Fine-grained PATs and GitHub App installation tokens return an empty header, making scope introspection impossible for those token types. There is no alternative API to query fine-grained PAT permissions. See: https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api#missing-or-incorrect-x-oauth-scopes-header

func (*LiveClient) GetWorkflow added in v0.19.0

func (c *LiveClient) GetWorkflow(ctx context.Context, owner, repo, workflowFile string) (*forge.Workflow, error)

GetWorkflow returns a workflow definition by filename (e.g. repo-maintenance.yml).

func (*LiveClient) GetWorkflowRun

func (c *LiveClient) GetWorkflowRun(ctx context.Context, owner, repo string, runID int) (*forge.WorkflowRun, error)

GetWorkflowRun returns a specific workflow run by ID.

func (*LiveClient) GetWorkflowRunAnnotations added in v0.13.0

func (c *LiveClient) GetWorkflowRunAnnotations(ctx context.Context, owner, repo string, runID int) ([]forge.Annotation, error)

GetWorkflowRunAnnotations returns annotations from all jobs in a workflow run. GitHub workflow commands (::notice::, ::warning::) produce check-run annotations that are accessible via the check-runs API.

func (*LiveClient) GetWorkflowRunLogs added in v0.0.3

func (c *LiveClient) GetWorkflowRunLogs(ctx context.Context, owner, repo string, runID int) (string, error)

GetWorkflowRunLogs downloads the logs for a workflow run. It fetches the job list for the run and concatenates each job's log output. When the output is not complete — more jobs than the single page of up to 100 fetched, or a job log over maxJobLogBytes — a "[job list truncated:" or "[log truncated:" note is embedded in the returned text.

func (*LiveClient) GrantProtectedBranchMergeUser added in v0.44.0

func (c *LiveClient) GrantProtectedBranchMergeUser(_ context.Context, _, _, _ string, _ int) error

GrantProtectedBranchMergeUser is not supported on GitHub.

func (*LiveClient) IsInstallationToken added in v0.24.0

func (c *LiveClient) IsInstallationToken(ctx context.Context) (bool, error)

IsInstallationToken reports whether the client's token is a GitHub App installation access token.

func (*LiveClient) IsProtectedBranch added in v0.31.0

func (c *LiveClient) IsProtectedBranch(ctx context.Context, owner, repo, branch string) (bool, error)

IsProtectedBranch checks whether the given branch has protection rules enabled on GitHub by querying the branch protection API endpoint. GitHub returns 404 both when a branch exists but is not protected and when the branch/repo does not exist. We distinguish the two by inspecting the API error message: "Branch not protected" means the branch exists but has no protection rules.

func (*LiveClient) ListDirectoryContents added in v0.17.0

func (c *LiveClient) ListDirectoryContents(ctx context.Context, owner, repo, path, ref string, recursive bool) ([]forge.DirectoryEntry, error)

ListDirectoryContents returns all files and subdirectories at the given path in a repository at the specified ref. When path points to a directory, the GitHub Contents API returns a JSON array of entries.

func (*LiveClient) ListInheritedRepoVariables added in v0.46.0

func (c *LiveClient) ListInheritedRepoVariables(ctx context.Context, owner, repo string) ([]forge.OrgVariable, error)

ListInheritedRepoVariables lists the organization variables available to a repository, honoring each variable's repository visibility (paginated).

func (*LiveClient) ListInstanceVariables added in v0.46.0

func (c *LiveClient) ListInstanceVariables(_ context.Context) ([]forge.OrgVariable, error)

ListInstanceVariables is not supported on GitHub.

func (*LiveClient) ListIssueComments added in v0.0.4

func (c *LiveClient) ListIssueComments(ctx context.Context, owner, repo string, number int) ([]forge.IssueComment, error)

ListIssueComments returns all comments on an issue, paginating automatically.

func (*LiveClient) ListIssueReactions added in v0.38.0

func (c *LiveClient) ListIssueReactions(ctx context.Context, owner, repo string, number int) ([]forge.Reaction, error)

ListIssueReactions returns the emoji reactions on an issue or pull request.

func (*LiveClient) ListOpenIssues added in v0.8.0

func (c *LiveClient) ListOpenIssues(ctx context.Context, owner, repo string, labels ...string) ([]forge.Issue, error)

ListOpenIssues returns open issues on a repository, excluding pull requests. When labels are provided, GitHub filters to issues carrying those labels.

func (*LiveClient) ListOrgInstallations

func (c *LiveClient) ListOrgInstallations(ctx context.Context, org string) ([]forge.Installation, error)

ListOrgInstallations lists app installations for an organization.

func (*LiveClient) ListOrgRepos

func (c *LiveClient) ListOrgRepos(ctx context.Context, org string, includePrivate bool) ([]forge.Repository, error)

ListOrgRepos returns non-archived, non-fork repositories for an org.

When includePrivate is false, private repos are also excluded.

When includePrivate is true, private repos are included. This is appropriate for per-repo installs where agents run on the target repo itself and logs are not publicly exposed.

Forks are excluded because fullsend's trust model assumes org-owned repos where CODEOWNERS governance and org-level permissions control agent autonomy. Fork repos may have different ownership and CODEOWNERS configs, which could bypass human-approval gates. Archived repos are excluded because they represent inactive targets where agent work would be wasted.

func (*LiveClient) ListOrgVariables added in v0.24.0

func (c *LiveClient) ListOrgVariables(ctx context.Context, org string) ([]forge.OrgVariable, error)

ListOrgVariables lists org-level Actions variables (paginated).

func (*LiveClient) ListPipelineSchedules added in v0.31.0

func (c *LiveClient) ListPipelineSchedules(_ context.Context, owner, repo string) ([]forge.PipelineSchedule, error)

ListPipelineSchedules is not supported on GitHub.

func (*LiveClient) ListPipelineTriggerTokens added in v0.44.0

func (c *LiveClient) ListPipelineTriggerTokens(_ context.Context, _, _ string) ([]forge.PipelineTriggerToken, error)

ListPipelineTriggerTokens is not supported on GitHub.

func (*LiveClient) ListProjectHooks added in v0.44.0

func (c *LiveClient) ListProjectHooks(_ context.Context, _, _ string) ([]forge.ProjectHook, error)

ListProjectHooks is not supported on GitHub.

func (*LiveClient) ListProtectedBranches added in v0.46.0

func (c *LiveClient) ListProtectedBranches(_ context.Context, _, _ string) ([]forge.ProtectedBranchRule, error)

ListProtectedBranches is not supported on GitHub.

func (*LiveClient) ListProtectedTags added in v0.46.0

func (c *LiveClient) ListProtectedTags(_ context.Context, _, _ string) ([]string, error)

ListProtectedTags is not supported on GitHub.

func (*LiveClient) ListPullRequestCommits added in v0.46.0

func (c *LiveClient) ListPullRequestCommits(ctx context.Context, owner, repo string, number int) ([]string, error)

ListPullRequestCommits returns the commit SHAs on a pull request, oldest first (the order GitHub's API reports them in). GitHub caps PR commit lists at 250 commits regardless of pagination.

func (*LiveClient) ListPullRequestFileDiffs added in v0.11.0

func (c *LiveClient) ListPullRequestFileDiffs(ctx context.Context, owner, repo string, number int) ([]forge.PullRequestFileDiff, error)

ListPullRequestFileDiffs returns the files changed by a pull request along with their unified diff patches. Same API endpoint as ListPullRequestFiles but also extracts the patch field.

func (*LiveClient) ListPullRequestFiles added in v0.8.5

func (c *LiveClient) ListPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]string, error)

ListPullRequestFiles returns the file paths changed by a pull request. GitHub caps PR file lists at 3000 files total regardless of pagination.

func (*LiveClient) ListPullRequestReviewThreads added in v0.46.0

func (c *LiveClient) ListPullRequestReviewThreads(ctx context.Context, owner, repo string, number int) (forge.ReviewThreadPage, error)

ListPullRequestReviewThreads returns the pull request's review threads and their comments through GitHub's GraphQL API. GitHub exposes review threads only through GraphQL, so keeping this operation here prevents callers from bypassing the forge abstraction with a raw `gh api` invocation.

func (*LiveClient) ListPullRequestReviews added in v0.2.0

func (c *LiveClient) ListPullRequestReviews(ctx context.Context, owner, repo string, number int) ([]forge.PullRequestReview, error)

ListPullRequestReviews returns all reviews on a pull request, paginating automatically.

func (*LiveClient) ListRecentWorkflowRuns added in v0.30.0

func (c *LiveClient) ListRecentWorkflowRuns(ctx context.Context, owner, repo string, perPage int) ([]forge.WorkflowRun, error)

ListRecentWorkflowRuns returns recent workflow runs across all workflows.

func (*LiveClient) ListRepoPullRequests

func (c *LiveClient) ListRepoPullRequests(ctx context.Context, owner, repo string) ([]forge.ChangeProposal, error)

ListRepoPullRequests lists open pull requests for a repository with pagination.

func (*LiveClient) ListRepoVariables added in v0.28.0

func (c *LiveClient) ListRepoVariables(ctx context.Context, owner, repo string) (map[string]string, error)

ListRepoVariables returns all Actions variables for a repository as a name-to-value map. Results are paginated; the method follows pagination until all variables are fetched or the safety page cap is reached.

func (*LiveClient) ListRepositoryArtifacts added in v0.30.0

func (c *LiveClient) ListRepositoryArtifacts(ctx context.Context, owner, repo string, perPage int) ([]forge.RepositoryArtifact, error)

ListRepositoryArtifacts returns recent artifacts stored for a repository.

func (*LiveClient) ListRepositoryFiles added in v0.30.0

func (c *LiveClient) ListRepositoryFiles(ctx context.Context, owner, repo string) ([]string, error)

ListRepositoryFiles returns all file paths in the default branch using the Git Trees API (single recursive call).

func (*LiveClient) ListWorkflowRunArtifacts added in v0.30.0

func (c *LiveClient) ListWorkflowRunArtifacts(ctx context.Context, owner, repo string, runID int) ([]forge.WorkflowArtifact, error)

ListWorkflowRunArtifacts returns artifacts uploaded by a workflow run.

func (*LiveClient) ListWorkflowRunJobs added in v0.34.0

func (c *LiveClient) ListWorkflowRunJobs(ctx context.Context, owner, repo string, runID int) ([]forge.WorkflowJob, error)

ListWorkflowRunJobs returns the jobs within a workflow run, paginating through as many 100-per-page requests as needed. A single per_page=100 request only ever returns the first page, so a run with more than 100 jobs (e.g. a large matrix build) could silently drop jobs beyond that page. Earliest-round selection (harnessRoundPollOnce) relies on this listing to find an agent's job within a run; a truncated listing could make it treat the agent as absent from the earliest eligible run and fall through to a later run instead (#7996 review).

owner and repo are escaped with url.PathEscape, as ListWorkflowRunsSince already does, since an unescaped delimiter (e.g. "#") would otherwise let the jobs suffix and pagination query be parsed as part of the path/query rather than a fragment (#7996 review).

func (*LiveClient) ListWorkflowRuns added in v0.0.3

func (c *LiveClient) ListWorkflowRuns(ctx context.Context, owner, repo, workflowFile string) ([]forge.WorkflowRun, error)

ListWorkflowRuns returns recent workflow runs for a workflow file.

func (*LiveClient) ListWorkflowRunsSince added in v0.45.0

func (c *LiveClient) ListWorkflowRunsSince(ctx context.Context, owner, repo, workflowFile string, since time.Time) ([]forge.WorkflowRun, error)

ListWorkflowRunsSince returns workflow runs for workflowFile created at or after since, paginating through as many 100-per-page requests as needed instead of ListWorkflowRuns's single per_page=10 request. GitHub orders runs newest-first, so once a page's run was created before since (or a short page signals the end of the listing), earlier pages cannot contain anything newer and pagination stops. Without this, earliest-round selection (harnessRoundPollOnce) could miss an eligible, unconsumed run that ten newer harness runs — for this agent or others — pushed past the first page (#7996 review).

func (*LiveClient) MergeChangeProposal added in v0.0.3

func (c *LiveClient) MergeChangeProposal(ctx context.Context, owner, repo string, number int) error

MergeChangeProposal squash-merges a pull request by number. If the merge fails with a 409 (head branch out of date), it updates the PR branch and retries up to 3 times with a short delay between attempts.

func (*LiveClient) MinimizeComment added in v0.2.0

func (c *LiveClient) MinimizeComment(ctx context.Context, nodeID, reason string) error

MinimizeComment minimizes (hides) an issue or review comment via the GitHub GraphQL API. The caller provides the GraphQL node ID directly (available in IssueComment.NodeID and PullRequestReview.NodeID). The reason must be one of: ABUSE, OFF_TOPIC, OUTDATED, RESOLVED, DUPLICATE, SPAM.

func (*LiveClient) OrgSecretExists

func (c *LiveClient) OrgSecretExists(ctx context.Context, org, name string) (bool, error)

OrgSecretExists checks if an org-level secret exists.

func (*LiveClient) RateLimit added in v0.38.0

func (c *LiveClient) RateLimit() (forge.RateLimit, bool)

RateLimit returns the most recent rate-limit state observed on a response from this client, and whether one has been observed yet.

func (*LiveClient) RepoSecretExists

func (c *LiveClient) RepoSecretExists(ctx context.Context, owner, repo, name string) (bool, error)

RepoSecretExists checks if a secret exists in a repository.

func (*LiveClient) RepoVariableExists

func (c *LiveClient) RepoVariableExists(ctx context.Context, owner, repo, name string) (bool, error)

RepoVariableExists checks if a variable exists in a repository.

func (*LiveClient) RevokePipelineTriggerToken added in v0.44.0

func (c *LiveClient) RevokePipelineTriggerToken(_ context.Context, _, _ string, _ int64) error

RevokePipelineTriggerToken is not supported on GitHub.

func (*LiveClient) RevokeProtectedBranchMergeUserEntry added in v0.48.0

func (c *LiveClient) RevokeProtectedBranchMergeUserEntry(_ context.Context, _, _, _ string, _, _ int) error

RevokeProtectedBranchMergeUserEntry is not supported on GitHub.

func (*LiveClient) SetPipelineVariablesMinimumOverrideRole added in v0.44.0

func (c *LiveClient) SetPipelineVariablesMinimumOverrideRole(_ context.Context, _, _, _ string) error

SetPipelineVariablesMinimumOverrideRole is not supported on GitHub.

func (*LiveClient) UpdateCIVariable added in v0.31.0

func (c *LiveClient) UpdateCIVariable(_ context.Context, _, _, _, _ string, _ bool) error

UpdateCIVariable is not supported on GitHub.

func (*LiveClient) UpdateFileIfMatch added in v0.49.0

func (c *LiveClient) UpdateFileIfMatch(ctx context.Context, owner, repo, path, message string, content []byte, expectedSHA string) error

UpdateFileIfMatch writes content through the Contents API with expectedSHA as the "sha" precondition (omitted to create only). GitHub rejects a stale SHA with 409 and a create over an existing file with a 422 naming the missing "sha"; both are returned wrapping forge.ErrConflict. The PUT is sent once: it bypasses retryOnRepoRace (which would replay a 409) and runs with forge.WithoutAmbiguousRetry so a timeout or 5xx is not replayed either.

func (*LiveClient) UpdateIssueComment added in v0.2.0

func (c *LiveClient) UpdateIssueComment(ctx context.Context, owner, repo string, commentID int, body string) error

UpdateIssueComment updates the body of an existing issue comment. See GetIssueComment for why owner and repo are percent-escaped.

func (*LiveClient) UpdatePipelineSchedule added in v0.44.0

func (c *LiveClient) UpdatePipelineSchedule(_ context.Context, _, _ string, _ int64, _ bool) error

UpdatePipelineSchedule is not supported on GitHub.

func (*LiveClient) UpdateProjectHook added in v0.44.0

func (c *LiveClient) UpdateProjectHook(_ context.Context, _, _ string, _ int64, _ forge.ProjectHook) (*forge.ProjectHook, error)

UpdateProjectHook is not supported on GitHub.

func (*LiveClient) UpdatePullRequestBranch added in v0.19.0

func (c *LiveClient) UpdatePullRequestBranch(ctx context.Context, owner, repo string, number int) error

UpdatePullRequestBranch updates a PR's head branch by merging the base branch into it (GitHub's PUT /repos/{owner}/{repo}/pulls/{number}/update-branch). The GitHub API returns 202 Accepted for this endpoint.

func (*LiveClient) UpdateRepoVisibility added in v0.33.0

func (c *LiveClient) UpdateRepoVisibility(ctx context.Context, owner, repo string, private bool) error

UpdateRepoVisibility sets a repository's visibility to public or private.

func (*LiveClient) WithAfterFunc added in v0.37.0

func (c *LiveClient) WithAfterFunc(f func(time.Duration) <-chan time.Time) *LiveClient

WithAfterFunc sets a custom delay function (for testing without real sleeps).

func (*LiveClient) WithBaseURL

func (c *LiveClient) WithBaseURL(url string) *LiveClient

WithBaseURL sets a custom base URL (for testing with httptest).

Jump to

Keyboard shortcuts

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