Documentation
¶
Overview ¶
Package forge defines the interface for interacting with git forges (GitHub, GitLab, Forgejo). All forge-specific operations flow through the Client interface, keeping the rest of the codebase forge-agnostic.
Index ¶
- Constants
- Variables
- func IsNotFound(err error) bool
- type ChangeProposal
- type Client
- type FakeClient
- func (f *FakeClient) CloseIssue(_ context.Context, _, _ string, _ int) error
- func (f *FakeClient) CreateBranch(_ context.Context, owner, repo, branchName string) error
- func (f *FakeClient) CreateChangeProposal(_ context.Context, owner, repo, title, body, head, base string) (*ChangeProposal, error)
- func (f *FakeClient) CreateFile(_ context.Context, owner, repo, path, message string, content []byte) error
- func (f *FakeClient) CreateFileOnBranch(_ context.Context, owner, repo, branch, path, message string, content []byte) error
- func (f *FakeClient) CreateIssue(_ context.Context, _, _, _, _ string) (*Issue, error)
- func (f *FakeClient) CreateOrUpdateFile(_ context.Context, owner, repo, path, message string, content []byte) error
- func (f *FakeClient) CreateOrUpdateFileOnBranch(_ context.Context, owner, repo, branch, path, message string, content []byte) error
- func (f *FakeClient) CreateOrUpdateRepoVariable(_ context.Context, owner, repo, name, value string) error
- func (f *FakeClient) CreateOrgSecret(_ context.Context, org, name, value string, selectedRepoIDs []int64) error
- func (f *FakeClient) CreateRepo(_ context.Context, org, name, description string, private bool) (*Repository, error)
- func (f *FakeClient) CreateRepoSecret(_ context.Context, owner, repo, name, value string) error
- func (f *FakeClient) DeleteOrgSecret(_ context.Context, org, name string) error
- func (f *FakeClient) DeleteRepo(_ context.Context, owner, repo string) error
- func (f *FakeClient) DispatchWorkflow(_ context.Context, _, _, _, _ string, _ map[string]string) error
- func (f *FakeClient) GetAppClientID(_ context.Context, slug string) (string, error)
- func (f *FakeClient) GetAuthenticatedUser(_ context.Context) (string, error)
- func (f *FakeClient) GetFileContent(_ context.Context, owner, repo, path string) ([]byte, error)
- func (f *FakeClient) GetLatestWorkflowRun(_ context.Context, owner, repo, workflowFile string) (*WorkflowRun, error)
- func (f *FakeClient) GetRepo(_ context.Context, owner, repo string) (*Repository, error)
- func (f *FakeClient) GetTokenScopes(_ context.Context) ([]string, error)
- func (f *FakeClient) GetWorkflowRun(_ context.Context, owner, repo string, runID int) (*WorkflowRun, error)
- func (f *FakeClient) GetWorkflowRunLogs(_ context.Context, _, _ string, _ int) (string, error)
- func (f *FakeClient) ListIssueComments(_ context.Context, _, _ string, _ int) ([]IssueComment, error)
- func (f *FakeClient) ListOrgInstallations(_ context.Context, _ string) ([]Installation, error)
- func (f *FakeClient) ListOrgRepos(_ context.Context, _ string) ([]Repository, error)
- func (f *FakeClient) ListRepoPullRequests(_ context.Context, owner, repo string) ([]ChangeProposal, error)
- func (f *FakeClient) ListWorkflowRuns(_ context.Context, owner, repo, workflowFile string) ([]WorkflowRun, error)
- func (f *FakeClient) MergeChangeProposal(_ context.Context, _, _ string, _ int) error
- func (f *FakeClient) OrgSecretExists(_ context.Context, org, name string) (bool, error)
- func (f *FakeClient) RepoSecretExists(_ context.Context, owner, repo, name string) (bool, error)
- func (f *FakeClient) RepoVariableExists(_ context.Context, owner, repo, name string) (bool, error)
- func (f *FakeClient) SetOrgSecretRepos(_ context.Context, org, name string, repoIDs []int64) error
- type FileRecord
- type Installation
- type Issue
- type IssueComment
- type OrgSecretRecord
- type Repository
- type SecretRecord
- type VariableRecord
- type WorkflowRun
Constants ¶
const ConfigRepoName = ".fullsend"
ConfigRepoName is the conventional name for the org-level fullsend configuration repository. See ADR-0003.
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound indicates a requested resource was not found on the forge.
Functions ¶
func IsNotFound ¶
IsNotFound reports whether err indicates a resource was not found.
Types ¶
type ChangeProposal ¶
ChangeProposal represents a pull request or merge request.
type Client ¶
type Client interface {
// Repository operations
ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
GetRepo(ctx context.Context, owner, repo string) (*Repository, error)
CreateRepo(ctx context.Context, org, name, description string, private bool) (*Repository, error)
DeleteRepo(ctx context.Context, owner, repo string) error
// File operations
CreateFile(ctx context.Context, owner, repo, path, message string, content []byte) error
// CreateOrUpdateFile creates a file or updates it if it already exists.
// On GitHub, updating an existing file requires the current file's SHA
// (optimistic concurrency control). The GitHub implementation handles
// this by fetching the existing SHA before writing. Without it, the
// API returns a 422 "sha wasn't supplied" error.
CreateOrUpdateFile(ctx context.Context, owner, repo, path, message string, content []byte) error
GetFileContent(ctx context.Context, owner, repo, path string) ([]byte, error)
// Branch operations
CreateBranch(ctx context.Context, owner, repo, branchName string) error
CreateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error
// CreateOrUpdateFileOnBranch creates or updates a file on a specific branch.
// Combines SHA-aware upsert with branch targeting.
CreateOrUpdateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error
// Change proposals (PRs/MRs)
CreateChangeProposal(ctx context.Context, owner, repo, title, body, head, base string) (*ChangeProposal, error)
ListRepoPullRequests(ctx context.Context, owner, repo string) ([]ChangeProposal, error)
// Authentication
GetAuthenticatedUser(ctx context.Context) (string, error)
// GetTokenScopes returns the OAuth scopes granted to the current token.
// On GitHub, this is read from the X-OAuth-Scopes response header.
// Returns nil (not an error) if the forge doesn't support scope introspection.
GetTokenScopes(ctx context.Context) ([]string, error)
// Secrets and variables
CreateRepoSecret(ctx context.Context, owner, repo, name, value string) error
RepoSecretExists(ctx context.Context, owner, repo, name string) (bool, error)
CreateOrUpdateRepoVariable(ctx context.Context, owner, repo, name, value string) error
RepoVariableExists(ctx context.Context, owner, repo, name string) (bool, error)
// Org-level secrets (for cross-repo dispatch tokens)
CreateOrgSecret(ctx context.Context, org, name, value string, selectedRepoIDs []int64) error
OrgSecretExists(ctx context.Context, org, name string) (bool, error)
DeleteOrgSecret(ctx context.Context, org, name string) error
SetOrgSecretRepos(ctx context.Context, org, name string, repoIDs []int64) error
// CI/Workflow operations
GetLatestWorkflowRun(ctx context.Context, owner, repo, workflowFile string) (*WorkflowRun, error)
GetWorkflowRun(ctx context.Context, owner, repo string, runID int) (*WorkflowRun, error)
DispatchWorkflow(ctx context.Context, owner, repo, workflowFile, ref string, inputs map[string]string) error
// Issue operations
CreateIssue(ctx context.Context, owner, repo, title, body string) (*Issue, error)
CloseIssue(ctx context.Context, owner, repo string, number int) error
ListIssueComments(ctx context.Context, owner, repo string, number int) ([]IssueComment, error)
// Change proposal merge
MergeChangeProposal(ctx context.Context, owner, repo string, number int) error
// Workflow run listing
ListWorkflowRuns(ctx context.Context, owner, repo, workflowFile string) ([]WorkflowRun, error)
// GetWorkflowRunLogs downloads the logs for a workflow run as plain text.
// On GitHub, this fetches job logs for each job in the run.
GetWorkflowRunLogs(ctx context.Context, owner, repo string, runID int) (string, error)
// App installation operations
ListOrgInstallations(ctx context.Context, org string) ([]Installation, error)
// GetAppClientID returns the Client ID for a GitHub App identified by slug.
GetAppClientID(ctx context.Context, slug string) (string, error)
}
Client abstracts all git forge operations. Implementations exist for GitHub (and eventually GitLab, Forgejo).
type FakeClient ¶
type FakeClient struct {
// Pre-populated data
Repos []Repository
FileContents map[string][]byte // key: "owner/repo/path"
WorkflowRuns map[string]*WorkflowRun // key: "owner/repo/workflow"
AuthenticatedUser string
Installations []Installation
Secrets map[string]bool // key: "owner/repo/name"
PullRequests map[string][]ChangeProposal // key: "owner/repo"
TokenScopes []string // scopes returned by GetTokenScopes
VariablesExist map[string]bool // key: "owner/repo/name"
// App client IDs for GetAppClientID
AppClientIDs map[string]string // key: app slug → client ID
// Org-level secret state
OrgSecrets map[string]bool // key: "org/name"
OrgSecretRepoIDs map[string][]int64 // key: "org/name" → repo IDs
// Error injection: key is method name, value is error to return.
Errors map[string]error
// Call recorders
CreatedRepos []Repository
CreatedFiles []FileRecord
CreatedBranches []string // "owner/repo/branch"
CreatedProposals []ChangeProposal
DeletedRepos []string // "owner/repo"
CreatedSecrets []SecretRecord
Variables []VariableRecord
DeletedOrgSecrets []string // "org/name"
CreatedOrgSecrets []OrgSecretRecord
// contains filtered or unexported fields
}
FakeClient is a thread-safe test double for forge.Client. Pre-populate its fields to control return values, and inspect recorder slices after the test to verify which calls were made.
func NewFakeClient ¶
func NewFakeClient() *FakeClient
NewFakeClient returns a FakeClient with all maps initialised.
func (*FakeClient) CloseIssue ¶ added in v0.0.3
func (*FakeClient) CreateBranch ¶
func (f *FakeClient) CreateBranch(_ context.Context, owner, repo, branchName string) error
func (*FakeClient) CreateChangeProposal ¶
func (f *FakeClient) CreateChangeProposal(_ context.Context, owner, repo, title, body, head, base string) (*ChangeProposal, error)
func (*FakeClient) CreateFile ¶
func (*FakeClient) CreateFileOnBranch ¶
func (*FakeClient) CreateIssue ¶ added in v0.0.3
func (*FakeClient) CreateOrUpdateFile ¶
func (*FakeClient) CreateOrUpdateFileOnBranch ¶
func (*FakeClient) CreateOrUpdateRepoVariable ¶
func (f *FakeClient) CreateOrUpdateRepoVariable(_ context.Context, owner, repo, name, value string) error
func (*FakeClient) CreateOrgSecret ¶
func (*FakeClient) CreateRepo ¶
func (f *FakeClient) CreateRepo(_ context.Context, org, name, description string, private bool) (*Repository, error)
func (*FakeClient) CreateRepoSecret ¶
func (f *FakeClient) CreateRepoSecret(_ context.Context, owner, repo, name, value string) error
func (*FakeClient) DeleteOrgSecret ¶
func (f *FakeClient) DeleteOrgSecret(_ context.Context, org, name string) error
func (*FakeClient) DeleteRepo ¶
func (f *FakeClient) DeleteRepo(_ context.Context, owner, repo string) error
func (*FakeClient) DispatchWorkflow ¶
func (*FakeClient) GetAppClientID ¶ added in v0.1.0
func (*FakeClient) GetAuthenticatedUser ¶
func (f *FakeClient) GetAuthenticatedUser(_ context.Context) (string, error)
func (*FakeClient) GetFileContent ¶
func (*FakeClient) GetLatestWorkflowRun ¶
func (f *FakeClient) GetLatestWorkflowRun(_ context.Context, owner, repo, workflowFile string) (*WorkflowRun, error)
func (*FakeClient) GetRepo ¶
func (f *FakeClient) GetRepo(_ context.Context, owner, repo string) (*Repository, error)
func (*FakeClient) GetTokenScopes ¶
func (f *FakeClient) GetTokenScopes(_ context.Context) ([]string, error)
func (*FakeClient) GetWorkflowRun ¶
func (f *FakeClient) GetWorkflowRun(_ context.Context, owner, repo string, runID int) (*WorkflowRun, error)
func (*FakeClient) GetWorkflowRunLogs ¶ added in v0.0.3
func (*FakeClient) ListIssueComments ¶ added in v0.0.4
func (f *FakeClient) ListIssueComments(_ context.Context, _, _ string, _ int) ([]IssueComment, error)
func (*FakeClient) ListOrgInstallations ¶
func (f *FakeClient) ListOrgInstallations(_ context.Context, _ string) ([]Installation, error)
func (*FakeClient) ListOrgRepos ¶
func (f *FakeClient) ListOrgRepos(_ context.Context, _ string) ([]Repository, error)
func (*FakeClient) ListRepoPullRequests ¶
func (f *FakeClient) ListRepoPullRequests(_ context.Context, owner, repo string) ([]ChangeProposal, error)
func (*FakeClient) ListWorkflowRuns ¶ added in v0.0.3
func (f *FakeClient) ListWorkflowRuns(_ context.Context, owner, repo, workflowFile string) ([]WorkflowRun, error)
func (*FakeClient) MergeChangeProposal ¶ added in v0.0.3
func (*FakeClient) OrgSecretExists ¶
func (*FakeClient) RepoSecretExists ¶
func (*FakeClient) RepoVariableExists ¶
func (*FakeClient) SetOrgSecretRepos ¶
type FileRecord ¶
FileRecord records a file creation/update call.
type Installation ¶
Installation represents an app installation on an org.
type IssueComment ¶ added in v0.0.4
IssueComment represents a comment on an issue.
type OrgSecretRecord ¶
OrgSecretRecord records an org-level secret creation call.
type Repository ¶
type Repository struct {
ID int64
Name string
FullName string
DefaultBranch string
Private bool
Archived bool
Fork bool
}
Repository represents a repository on a git forge.
type SecretRecord ¶
type SecretRecord struct {
Owner, Repo, Name, Value string
}
SecretRecord records a secret creation call.
type VariableRecord ¶
type VariableRecord struct {
Owner, Repo, Name, Value string
}
VariableRecord records a variable creation/update call.