Documentation
¶
Overview ¶
Package github implements forge.Client for the GitHub REST API.
Index ¶
- Constants
- Variables
- func DefaultAgentRoles() []string
- func IsPATForbiddenError(err error) bool
- func IsRateLimitError(err error) bool
- func IsServerError(err error) bool
- func ListInstallationRepositories(ctx context.Context, httpClient *http.Client, baseURL, token string, ...) (repos []string, totalCount int, ok bool, err error)
- func ProbeInstallationToken(ctx context.Context, httpClient *http.Client, baseURL, token string) (bool, error)
- func RetryAfterFromError(err error) (d time.Duration, ok bool)
- type APIError
- type APIErrorDetail
- type AppConfig
- type AppPermissions
- type HookAttributes
- type LiveClient
- func (c *LiveClient) APICalls() map[string]int64
- func (c *LiveClient) APIQuotaCounters() []forge.APIQuotaCounter
- func (c *LiveClient) AddCollaborator(ctx context.Context, owner, repo, username, permission string) error
- func (c *LiveClient) AddIssueCommentReaction(ctx context.Context, owner, repo string, commentID int, content string) (int64, error)
- func (c *LiveClient) AddIssueLabels(ctx context.Context, owner, repo string, number int, labels ...string) error
- func (c *LiveClient) AddIssueReaction(ctx context.Context, owner, repo string, number int, content string) (int64, error)
- func (c *LiveClient) BaseURL() string
- func (c *LiveClient) CloseChangeProposal(ctx context.Context, owner, repo string, number int) error
- func (c *LiveClient) CloseIssue(ctx context.Context, owner, repo string, number int) error
- func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message string, files []forge.TreeFile) (bool, error)
- func (c *LiveClient) CommitFilesToBranch(ctx context.Context, owner, repo, branch, message string, ...) (bool, error)
- func (c *LiveClient) CompareCommits(ctx context.Context, owner, repo, base, head string) (string, error)
- func (c *LiveClient) CreateBranch(ctx context.Context, owner, repo, branchName string) error
- func (c *LiveClient) CreateBranchFromSHA(ctx context.Context, owner, repo, branchName, sha string) error
- func (c *LiveClient) CreateChangeProposal(ctx context.Context, owner, repo, title, body, head, base string) (*forge.ChangeProposal, error)
- func (c *LiveClient) CreateCrossRepoChangeProposal(ctx context.Context, ...) (*forge.ChangeProposal, error)
- func (c *LiveClient) CreateFile(ctx context.Context, owner, repo, path, message string, content []byte) error
- func (c *LiveClient) CreateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error
- func (c *LiveClient) CreateFork(ctx context.Context, owner, repo string) (string, string, error)
- func (c *LiveClient) CreateForkInOrg(ctx context.Context, owner, repo, org, forkName string) (string, error)
- func (c *LiveClient) CreateIssue(ctx context.Context, owner, repo, title, body string, labels ...string) (*forge.Issue, error)
- func (c *LiveClient) CreateIssueComment(ctx context.Context, owner, repo string, number int, body string) (*forge.IssueComment, error)
- func (c *LiveClient) CreateOrUpdateFile(ctx context.Context, owner, repo, path, message string, content []byte) error
- func (c *LiveClient) CreateOrUpdateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error
- func (c *LiveClient) CreateOrUpdateOrgVariableAll(ctx context.Context, org, name, value string) error
- func (c *LiveClient) CreateOrUpdateRepoVariable(ctx context.Context, owner, repo, name, value string) error
- func (c *LiveClient) CreatePipeline(_ context.Context, _, _, _ string, _ map[string]string) (*forge.Pipeline, error)
- func (c *LiveClient) CreatePipelineSchedule(_ context.Context, owner, repo, ref, description, cron string, ...) (int64, error)
- func (c *LiveClient) CreatePipelineScheduleWithActive(_ context.Context, owner, repo, ref, description, cron string, ...) (int64, error)
- func (c *LiveClient) CreatePipelineTriggerToken(_ context.Context, _, _, _ string) (*forge.PipelineTriggerToken, error)
- func (c *LiveClient) CreatePipelineWithInputs(_ context.Context, _, _, _ string, _ map[string]forge.PipelineInputValue) (*forge.Pipeline, error)
- func (c *LiveClient) CreateProjectHook(_ context.Context, _, _ string, _ forge.ProjectHook) (*forge.ProjectHook, error)
- func (c *LiveClient) CreateProtectedCIVariable(_ context.Context, _, _, _, _ string) error
- func (c *LiveClient) CreatePullRequestReview(ctx context.Context, owner, repo string, number int, ...) error
- func (c *LiveClient) CreateRepo(ctx context.Context, org, name, description string, private bool) (*forge.Repository, error)
- func (c *LiveClient) CreateRepoSecret(ctx context.Context, owner, repo, name, value string) error
- func (c *LiveClient) DeleteBranch(ctx context.Context, owner, repo, branchName string) error
- func (c *LiveClient) DeleteFile(ctx context.Context, owner, repo, path, message string) error
- func (c *LiveClient) DeleteFiles(ctx context.Context, owner, repo, message string, paths []string) (int, error)
- func (c *LiveClient) DeleteIssueComment(ctx context.Context, owner, repo string, commentID int) error
- func (c *LiveClient) DeleteIssueCommentReaction(ctx context.Context, owner, repo string, commentID int, reactionID int64) error
- func (c *LiveClient) DeleteIssueReaction(ctx context.Context, owner, repo string, number int, reactionID int64) error
- func (c *LiveClient) DeleteOrgSecret(ctx context.Context, org, name string) error
- func (c *LiveClient) DeleteOrgVariable(ctx context.Context, org, name string) error
- func (c *LiveClient) DeletePipelineSchedule(_ context.Context, owner, repo string, scheduleID int64) error
- func (c *LiveClient) DeleteProjectHook(_ context.Context, _, _ string, _ int64) error
- func (c *LiveClient) DeleteProjectServiceAccount(_ context.Context, _, _ string, _ int) error
- func (c *LiveClient) DeleteRef(ctx context.Context, owner, repo, refPath string) error
- func (c *LiveClient) DeleteRepo(ctx context.Context, owner, repo string) error
- func (c *LiveClient) DeleteRepoSecret(ctx context.Context, owner, repo, name string) error
- func (c *LiveClient) DeleteRepoVariable(ctx context.Context, owner, repo, name string) error
- func (c *LiveClient) DismissPullRequestReview(ctx context.Context, owner, repo string, number, reviewID int, message string) error
- func (c *LiveClient) DispatchWorkflow(ctx context.Context, owner, repo, workflowFile, ref string, ...) error
- func (c *LiveClient) DownloadWorkflowRunArtifact(ctx context.Context, owner, repo string, artifactID int) ([]byte, error)
- func (c *LiveClient) EnsureLabel(ctx context.Context, owner, repo, name string) error
- func (c *LiveClient) FindExistingFork(ctx context.Context, owner, repo string) (string, string, error)
- func (c *LiveClient) ForceCommitFileToBranch(_ context.Context, _, _, _, _, _ string, _ []byte) error
- func (c *LiveClient) GetAppClientID(ctx context.Context, slug string) (string, error)
- func (c *LiveClient) GetAuthenticatedUser(ctx context.Context) (string, error)
- func (c *LiveClient) GetAuthenticatedUserIdentity(ctx context.Context) (*forge.UserIdentity, error)
- func (c *LiveClient) GetBranchRef(ctx context.Context, owner, repo, branch string) (string, error)
- func (c *LiveClient) GetCollaboratorPermission(ctx context.Context, owner, repo, username string) (string, error)
- func (c *LiveClient) GetCollaboratorPermissionDetail(ctx context.Context, owner, repo, username string) (forge.GitHubCollaboratorPermissionDetail, error)
- func (c *LiveClient) GetFileContent(ctx context.Context, owner, repo, path string) ([]byte, error)
- func (c *LiveClient) GetFileContentAtRef(ctx context.Context, owner, repo, path, ref string) ([]byte, error)
- func (c *LiveClient) GetIssue(ctx context.Context, owner, repo string, number int) (*forge.Issue, error)
- func (c *LiveClient) GetIssueComment(ctx context.Context, owner, repo string, commentID int) (*forge.IssueComment, error)
- func (c *LiveClient) GetJobTokenRepositoryPushAllowed(_ context.Context, _, _ string) (bool, error)
- func (c *LiveClient) GetLatestWorkflowRun(ctx context.Context, owner, repo, workflowFile string) (*forge.WorkflowRun, error)
- func (c *LiveClient) GetOrgMembership(ctx context.Context, org, username string) (forge.OrgMembership, error)
- func (c *LiveClient) GetOrgPlan(ctx context.Context, org string) (string, error)
- func (c *LiveClient) GetOrgVariable(ctx context.Context, org, name string) (string, bool, error)
- func (c *LiveClient) GetPipelineSchedule(_ context.Context, _, _ string, _ int64) (*forge.PipelineSchedule, error)
- func (c *LiveClient) GetPipelineVariablesMinimumOverrideRole(_ context.Context, _, _ string) (string, error)
- func (c *LiveClient) GetProjectMemberAccessLevel(_ context.Context, _, _ string, _ int64) (int, error)
- func (c *LiveClient) GetProtectedBranch(_ context.Context, _, _, _ string) (*forge.ProtectedBranchRule, error)
- func (c *LiveClient) GetPullRequestAuthorizationContext(ctx context.Context, owner, repo string, number int) (*forge.PullRequestAuthorizationContext, error)
- func (c *LiveClient) GetPullRequestHeadSHA(ctx context.Context, owner, repo string, number int) (string, error)
- func (c *LiveClient) GetPullRequestInfo(ctx context.Context, owner, repo string, number int) (*forge.PullRequestInfo, error)
- func (c *LiveClient) GetPushRuleBranchNameRegex(_ context.Context, _, _ string) (string, error)
- func (c *LiveClient) GetRawFileContentAtRef(ctx context.Context, owner, repo, path, ref string) ([]byte, error)
- func (c *LiveClient) GetRef(ctx context.Context, owner, repo, refPath string) (string, error)
- func (c *LiveClient) GetRepo(ctx context.Context, owner, repo string) (*forge.Repository, error)
- func (c *LiveClient) GetRepoSecretProtection(ctx context.Context, owner, repo, name string) (forge.SecretProtection, error)
- func (c *LiveClient) GetRepoVariable(ctx context.Context, owner, repo, name string) (string, bool, error)
- func (c *LiveClient) GetRepoVariableInfo(ctx context.Context, owner, repo, name string) (forge.RepoVariable, bool, error)
- func (c *LiveClient) GetTokenScopes(ctx context.Context) ([]string, error)
- func (c *LiveClient) GetWorkflow(ctx context.Context, owner, repo, workflowFile string) (*forge.Workflow, error)
- func (c *LiveClient) GetWorkflowRun(ctx context.Context, owner, repo string, runID int) (*forge.WorkflowRun, error)
- func (c *LiveClient) GetWorkflowRunAnnotations(ctx context.Context, owner, repo string, runID int) ([]forge.Annotation, error)
- func (c *LiveClient) GetWorkflowRunLogs(ctx context.Context, owner, repo string, runID int) (string, error)
- func (c *LiveClient) GrantProtectedBranchMergeUser(_ context.Context, _, _, _ string, _ int) error
- func (c *LiveClient) IsInstallationToken(ctx context.Context) (bool, error)
- func (c *LiveClient) IsProtectedBranch(ctx context.Context, owner, repo, branch string) (bool, error)
- func (c *LiveClient) ListDirectoryContents(ctx context.Context, owner, repo, path, ref string, recursive bool) ([]forge.DirectoryEntry, error)
- func (c *LiveClient) ListInheritedRepoVariables(ctx context.Context, owner, repo string) ([]forge.OrgVariable, error)
- func (c *LiveClient) ListInstanceVariables(_ context.Context) ([]forge.OrgVariable, error)
- func (c *LiveClient) ListIssueComments(ctx context.Context, owner, repo string, number int) ([]forge.IssueComment, error)
- func (c *LiveClient) ListIssueLabelEvents(ctx context.Context, owner, repo string, number int) ([]forge.IssueLabelEvent, error)
- func (c *LiveClient) ListIssueReactions(ctx context.Context, owner, repo string, number int) ([]forge.Reaction, error)
- func (c *LiveClient) ListOpenIssues(ctx context.Context, owner, repo string, labels ...string) ([]forge.Issue, error)
- func (c *LiveClient) ListOrgInstallations(ctx context.Context, org string) ([]forge.Installation, error)
- func (c *LiveClient) ListOrgRepos(ctx context.Context, org string, includePrivate bool) ([]forge.Repository, error)
- func (c *LiveClient) ListOrgVariables(ctx context.Context, org string) ([]forge.OrgVariable, error)
- func (c *LiveClient) ListPipelineSchedules(_ context.Context, owner, repo string) ([]forge.PipelineSchedule, error)
- func (c *LiveClient) ListPipelineTriggerTokens(_ context.Context, _, _ string) ([]forge.PipelineTriggerToken, error)
- func (c *LiveClient) ListProjectHooks(_ context.Context, _, _ string) ([]forge.ProjectHook, error)
- func (c *LiveClient) ListProtectedBranches(_ context.Context, _, _ string) ([]forge.ProtectedBranchRule, error)
- func (c *LiveClient) ListProtectedTags(_ context.Context, _, _ string) ([]string, error)
- func (c *LiveClient) ListPullRequestCommits(ctx context.Context, owner, repo string, number int) ([]string, error)
- func (c *LiveClient) ListPullRequestFileDiffs(ctx context.Context, owner, repo string, number int) ([]forge.PullRequestFileDiff, error)
- func (c *LiveClient) ListPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]string, error)
- func (c *LiveClient) ListPullRequestReviewThreads(ctx context.Context, owner, repo string, number int) (forge.ReviewThreadPage, error)
- func (c *LiveClient) ListPullRequestReviews(ctx context.Context, owner, repo string, number int) ([]forge.PullRequestReview, error)
- func (c *LiveClient) ListRecentWorkflowRuns(ctx context.Context, owner, repo string, perPage int) ([]forge.WorkflowRun, error)
- func (c *LiveClient) ListRepoPullRequests(ctx context.Context, owner, repo string) ([]forge.ChangeProposal, error)
- func (c *LiveClient) ListRepoVariables(ctx context.Context, owner, repo string) (map[string]string, error)
- func (c *LiveClient) ListRepositoryArtifacts(ctx context.Context, owner, repo string, perPage int) ([]forge.RepositoryArtifact, error)
- func (c *LiveClient) ListRepositoryFiles(ctx context.Context, owner, repo string) ([]string, error)
- func (c *LiveClient) ListWorkflowRunArtifacts(ctx context.Context, owner, repo string, runID int) ([]forge.WorkflowArtifact, error)
- func (c *LiveClient) ListWorkflowRunJobs(ctx context.Context, owner, repo string, runID int) ([]forge.WorkflowJob, error)
- func (c *LiveClient) ListWorkflowRuns(ctx context.Context, owner, repo, workflowFile string) ([]forge.WorkflowRun, error)
- func (c *LiveClient) ListWorkflowRunsSince(ctx context.Context, owner, repo, workflowFile string, since time.Time) ([]forge.WorkflowRun, error)
- func (c *LiveClient) MergeChangeProposal(ctx context.Context, owner, repo string, number int) error
- func (c *LiveClient) MinimizeComment(ctx context.Context, nodeID, reason string) error
- func (c *LiveClient) OrgSecretExists(ctx context.Context, org, name string) (bool, error)
- func (c *LiveClient) RateLimit() (forge.RateLimit, bool)
- func (c *LiveClient) RemoveIssueLabel(ctx context.Context, owner, repo string, number int, label string) error
- func (c *LiveClient) RepoSecretExists(ctx context.Context, owner, repo, name string) (bool, error)
- func (c *LiveClient) RepoVariableExists(ctx context.Context, owner, repo, name string) (bool, error)
- func (c *LiveClient) RevokePipelineTriggerToken(_ context.Context, _, _ string, _ int64) error
- func (c *LiveClient) RevokeProtectedBranchMergeUserEntry(_ context.Context, _, _, _ string, _, _ int) error
- func (c *LiveClient) SetPipelineVariablesMinimumOverrideRole(_ context.Context, _, _, _ string) error
- func (c *LiveClient) UpdateCIVariable(_ context.Context, _, _, _, _ string, _ bool) error
- func (c *LiveClient) UpdateFileIfMatch(ctx context.Context, owner, repo, path, message string, content []byte, ...) error
- func (c *LiveClient) UpdateIssueComment(ctx context.Context, owner, repo string, commentID int, body string) error
- func (c *LiveClient) UpdatePipelineSchedule(_ context.Context, _, _ string, _ int64, _ bool) error
- func (c *LiveClient) UpdateProjectHook(_ context.Context, _, _ string, _ int64, _ forge.ProjectHook) (*forge.ProjectHook, error)
- func (c *LiveClient) UpdatePullRequestBranch(ctx context.Context, owner, repo string, number int) error
- func (c *LiveClient) UpdateRepoVisibility(ctx context.Context, owner, repo string, private bool) error
- func (c *LiveClient) WithAfterFunc(f func(time.Duration) <-chan time.Time) *LiveClient
- func (c *LiveClient) WithBaseURL(url string) *LiveClient
- func (c *LiveClient) WithSameOriginRedirects() *LiveClient
Constants ¶
const ( RetryGiveUpPrefix = "retryable error after " ServerErrorNotRetriedPrefix = "server error on " )
do() ends a retryable failure it stops on with a message that starts with one of these prefixes: RetryGiveUpPrefix when its retries are used up, and ServerErrorNotRetriedPrefix when it does not resend a 5xx because the request may already have been applied (forge.WithoutAmbiguousRetry). The behaviour harness matches this wording in `fullsend github setup` output, where no typed APIError survives the subprocess boundary, so reword these only together with the tests that pin them.
Variables ¶
var ErrInvitationPending = errors.New("invitation pending")
ErrInvitationPending reports that AddCollaborator's PUT answered 201: GitHub sent an invitation, and access starts only once the invitee accepts it. Match it with errors.Is.
Functions ¶
func DefaultAgentRoles ¶
func DefaultAgentRoles() []string
DefaultAgentRoles returns the standard set of agent roles.
func IsPATForbiddenError ¶ added in v0.30.0
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
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 IsServerError ¶ added in v0.56.1
IsServerError reports whether err itself is a GitHub server error: an *APIError with status 500–504 and no context cause (the condition APIError.IsTransient uses for those statuses), or a GraphQL error with an empty type and GitHub's generic server-error message. It does not unwrap err, so callers that walk an error tree node by node keep each errors.Join branch independent.
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.
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) IsTransient ¶ added in v0.37.0
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 ¶
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 ¶
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 ¶
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) APICalls ¶ added in v0.55.0
func (c *LiveClient) APICalls() map[string]int64
APICalls returns how many responses this client has received, by forge.APICaller label. Every attempt of a retried request counts. A 304 does not, because it costs no primary quota, and neither does a request that got no response. A response charged to a quota other than core, such as graphql, counts under "caller/resource".
func (*LiveClient) APIQuotaCounters ¶ added in v0.55.0
func (c *LiveClient) APIQuotaCounters() []forge.APIQuotaCounter
APIQuotaCounters returns the groups of core rate-limit readings this client has seen and its calls in each. It counts the core responses APICalls counts, except those without a usable X-RateLimit-Remaining or X-RateLimit-Reset, which belong to no group. As in APICalls, a response with no X-RateLimit-Resource counts as core.
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
CloseChangeProposal closes an open pull request without merging it.
func (*LiveClient) CloseIssue ¶ added in v0.0.3
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
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
DeleteProjectHook is not supported on GitHub.
func (*LiveClient) DeleteProjectServiceAccount ¶ added in v0.46.0
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) EnsureLabel ¶ added in v0.56.0
func (c *LiveClient) EnsureLabel(ctx context.Context, owner, repo, name string) error
EnsureLabel creates a repository label. GitHub answers 422 with an already_exists validation error when the label exists; that is success.
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 (*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
GetBranchRef returns the HEAD commit SHA for the named branch.
func (*LiveClient) GetCollaboratorPermission ¶ added in v0.31.0
func (*LiveClient) GetCollaboratorPermissionDetail ¶ added in v0.55.0
func (c *LiveClient) GetCollaboratorPermissionDetail(ctx context.Context, owner, repo, username string) (forge.GitHubCollaboratorPermissionDetail, error)
func (*LiveClient) GetFileContent ¶
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
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
GetOrgPlan returns the billing plan name for the org (e.g. "free", "team", "enterprise").
func (*LiveClient) GetOrgVariable ¶ added in v0.24.0
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) GetPullRequestAuthorizationContext ¶ added in v0.55.0
func (c *LiveClient) GetPullRequestAuthorizationContext(ctx context.Context, owner, repo string, number int) (*forge.PullRequestAuthorizationContext, error)
GetPullRequestAuthorizationContext returns fields used by the e2e CI gate.
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
GetPushRuleBranchNameRegex is not supported on GitHub.
func (*LiveClient) GetRawFileContentAtRef ¶ added in v0.57.0
func (c *LiveClient) GetRawFileContentAtRef(ctx context.Context, owner, repo, path, ref string) ([]byte, error)
GetRawFileContentAtRef retrieves the content of a file at a specific ref like GetFileContentAtRef, but requests the raw media type and rejects paths that are not files. It is used where a file must be read through a GitHub host's contents API in full, for example the agents-repo fallback on a GitHub host other than github.com.
The file is requested with the raw media type, so files the base64 JSON representation cannot carry (GitHub serves those as content: "", encoding: "none" — every file over 1 MiB) are still returned.
On github.com a raw file is never served as application/json, so the JSON handling below is defensive, for servers that ignore the raw media type and answer with the JSON representation instead. Such a body is read as that representation only when it unmistakably is one: a directory listing (a non-empty array of entries, each with type, path and sha) or a symlink or submodule entry errors, as it did before the raw media type; a type "file" object with an encoding of base64 or none and a content key is decoded as the contents envelope. Any other JSON body — a raw JSON file such as a schema, a manifest or ["bug"] — is returned as the file's own bytes, never decoded into empty content.
func (*LiveClient) GetRef ¶ added in v0.29.0
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; a skipped job is listed with no log. 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
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) ListIssueLabelEvents ¶ added in v0.55.0
func (c *LiveClient) ListIssueLabelEvents(ctx context.Context, owner, repo string, number int) ([]forge.IssueLabelEvent, error)
ListIssueLabelEvents returns labeled events on an issue or pull request.
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
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
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. It paginates like ListWorkflowRunJobs so runs with more than one page of artifacts (e.g. large dispatch matrices) are returned in full.
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
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 ¶
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) RemoveIssueLabel ¶ added in v0.55.0
func (c *LiveClient) RemoveIssueLabel(ctx context.Context, owner, repo string, number int, label string) error
RemoveIssueLabel removes a label from an issue or pull request.
func (*LiveClient) RepoSecretExists ¶
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
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
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
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).
func (*LiveClient) WithSameOriginRedirects ¶ added in v0.57.0
func (c *LiveClient) WithSameOriginRedirects() *LiveClient
WithSameOriginRedirects makes the client follow an HTTP redirect only to the same scheme, host (compared lowercased) and port as the request that was redirected, as GitHub does with same-host 301s for renamed repositories, and refuse any other redirect — another host, a subdomain, a different port or an https-to-http downgrade — with an error. Go's default policy follows those and keeps the Authorization header on same-host and subdomain hops, so a client sending its token to a host other than github.com uses this. The client's transport and timeout are kept.