github

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: May 8, 2026 License: Apache-2.0 Imports: 15 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.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an error response from the GitHub API.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Unwrap 

func (e *APIError) Unwrap() error

Unwrap returns forge.ErrNotFound for 404 errors, enabling errors.Is checks.

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 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"`
	Workflows            string `json:"workflows,omitempty"`
	Administration       string `json:"administration,omitempty"`
	Members              string `json:"members,omitempty"`
	OrganizationProjects string `json:"organization_projects,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.

func New 

func New(token string) *LiveClient

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

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 using the Git Trees/Blobs/Commits API. Returns (false, nil) when all files already match the current tree (idempotent).

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) CreateChangeProposal 

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

CreateChangeProposal creates a pull request.

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) CreateIssue added in v0.0.3 

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

CreateIssue creates a new issue on a repository.

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) CreateOrUpdateRepoVariable 

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

CreateOrUpdateRepoVariable creates or updates a repository Actions variable.

func (*LiveClient) CreateOrgSecret 

func (c *LiveClient) CreateOrgSecret(ctx context.Context, org, name, value string, selectedRepoIDs []int64) error

CreateOrgSecret creates or updates an encrypted organization-level secret scoped to the given repository IDs. The value is trimmed of whitespace before encryption to prevent corruption from stray newlines or carriage returns in pasted input.

func (*LiveClient) CreatePullRequestReview added in v0.2.0 

func (c *LiveClient) CreatePullRequestReview(ctx context.Context, owner, repo string, number int, event, body, commitSHA string) 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.

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) 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) 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) DeleteRepo 

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

DeleteRepo deletes a repository.

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) 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.

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) 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) GetOrgSecretRepos added in v0.5.0 

func (c *LiveClient) GetOrgSecretRepos(ctx context.Context, org, name string) ([]int64, error)

GetOrgSecretRepos returns the repository IDs that have access to an org secret.

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) 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) 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) 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) 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.

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) 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) ([]forge.Repository, error)

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

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) 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) 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) 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) 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.

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) 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) SetOrgSecretRepos 

func (c *LiveClient) SetOrgSecretRepos(ctx context.Context, org, name string, repoIDs []int64) error

SetOrgSecretRepos sets the list of repositories that can access an org secret.

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.

func (*LiveClient) WithBaseURL 

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

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.