Documentation
¶
Overview ¶
Package github implements forge.Client for the GitHub REST API.
Index ¶
- func DefaultAgentRoles() []string
- type APIError
- type AppConfig
- type AppPermissions
- type HookAttributes
- type LiveClient
- func (c *LiveClient) CloseIssue(ctx context.Context, owner, repo string, number int) error
- func (c *LiveClient) CreateBranch(ctx context.Context, owner, repo, branchName string) error
- func (c *LiveClient) CreateChangeProposal(ctx context.Context, owner, repo, title, body, head, base string) (*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) CreateIssue(ctx context.Context, owner, repo, title, body string) (*forge.Issue, 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) CreateOrUpdateRepoVariable(ctx context.Context, owner, repo, name, value string) error
- func (c *LiveClient) CreateOrgSecret(ctx context.Context, org, name, value string, selectedRepoIDs []int64) 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) DeleteOrgSecret(ctx context.Context, org, name string) error
- func (c *LiveClient) DeleteRepo(ctx context.Context, owner, repo string) error
- func (c *LiveClient) DispatchWorkflow(ctx context.Context, owner, repo, workflowFile, ref string, ...) error
- func (c *LiveClient) GetAppClientID(ctx context.Context, slug string) (string, error)
- func (c *LiveClient) GetAuthenticatedUser(ctx context.Context) (string, error)
- func (c *LiveClient) GetFileContent(ctx context.Context, owner, repo, path string) ([]byte, error)
- func (c *LiveClient) GetLatestWorkflowRun(ctx context.Context, owner, repo, workflowFile string) (*forge.WorkflowRun, error)
- func (c *LiveClient) GetRepo(ctx context.Context, owner, repo string) (*forge.Repository, error)
- func (c *LiveClient) GetTokenScopes(ctx context.Context) ([]string, error)
- func (c *LiveClient) GetWorkflowRun(ctx context.Context, owner, repo string, runID int) (*forge.WorkflowRun, error)
- func (c *LiveClient) GetWorkflowRunLogs(ctx context.Context, owner, repo string, runID int) (string, error)
- func (c *LiveClient) ListIssueComments(ctx context.Context, owner, repo string, number int) ([]forge.IssueComment, error)
- func (c *LiveClient) ListOrgInstallations(ctx context.Context, org string) ([]forge.Installation, error)
- func (c *LiveClient) ListOrgRepos(ctx context.Context, org string) ([]forge.Repository, error)
- func (c *LiveClient) ListRepoPullRequests(ctx context.Context, owner, repo string) ([]forge.ChangeProposal, error)
- func (c *LiveClient) ListWorkflowRuns(ctx context.Context, owner, repo, workflowFile string) ([]forge.WorkflowRun, error)
- func (c *LiveClient) MergeChangeProposal(ctx context.Context, owner, repo string, number int) error
- func (c *LiveClient) OrgSecretExists(ctx context.Context, org, name string) (bool, 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) SetOrgSecretRepos(ctx context.Context, org, name string, repoIDs []int64) error
- func (c *LiveClient) WithBaseURL(url string) *LiveClient
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 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 {
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"`
}
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.
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
CloseIssue closes an issue by number.
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) 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) 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) 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) 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 (*LiveClient) GetAuthenticatedUser ¶
func (c *LiveClient) GetAuthenticatedUser(ctx context.Context) (string, error)
GetAuthenticatedUser returns the login of the authenticated user.
func (*LiveClient) GetFileContent ¶
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) 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 up to 100 comments on an issue (single page, no pagination).
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.
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
MergeChangeProposal squash-merges a pull request by number.
func (*LiveClient) OrgSecretExists ¶
OrgSecretExists checks if an org-level secret exists.
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) 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) WithBaseURL ¶
func (c *LiveClient) WithBaseURL(url string) *LiveClient
WithBaseURL sets a custom base URL (for testing with httptest).