forge

package
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Apr 17, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

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

View Source
const ConfigRepoName = ".fullsend"

ConfigRepoName is the conventional name for the org-level fullsend configuration repository. See ADR-0003.

Variables

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound indicates a requested resource was not found on the forge.

Functions

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err indicates a resource was not found.

Types

type ChangeProposal

type ChangeProposal struct {
	URL    string
	Title  string
	Number int
}

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

	// App installation operations
	ListOrgInstallations(ctx context.Context, org string) ([]Installation, 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"

	// 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) 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 (f *FakeClient) CreateFile(_ context.Context, owner, repo, path, message string, content []byte) error

func (*FakeClient) CreateFileOnBranch

func (f *FakeClient) CreateFileOnBranch(_ context.Context, owner, repo, branch, path, message string, content []byte) error

func (*FakeClient) CreateOrUpdateFile

func (f *FakeClient) CreateOrUpdateFile(_ context.Context, owner, repo, path, message string, content []byte) error

func (*FakeClient) CreateOrUpdateFileOnBranch

func (f *FakeClient) CreateOrUpdateFileOnBranch(_ context.Context, owner, repo, branch, path, message string, content []byte) error

func (*FakeClient) CreateOrUpdateRepoVariable

func (f *FakeClient) CreateOrUpdateRepoVariable(_ context.Context, owner, repo, name, value string) error

func (*FakeClient) CreateOrgSecret

func (f *FakeClient) CreateOrgSecret(_ context.Context, org, name, value string, selectedRepoIDs []int64) error

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 (f *FakeClient) DispatchWorkflow(_ context.Context, _, _, _, _ string, _ map[string]string) error

func (*FakeClient) GetAuthenticatedUser

func (f *FakeClient) GetAuthenticatedUser(_ context.Context) (string, error)

func (*FakeClient) GetFileContent

func (f *FakeClient) GetFileContent(_ context.Context, owner, repo, path string) ([]byte, error)

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

func (f *FakeClient) OrgSecretExists(_ context.Context, org, name string) (bool, error)

func (*FakeClient) RepoSecretExists

func (f *FakeClient) RepoSecretExists(_ context.Context, owner, repo, name string) (bool, error)

func (*FakeClient) RepoVariableExists

func (f *FakeClient) RepoVariableExists(_ context.Context, owner, repo, name string) (bool, error)

func (*FakeClient) SetOrgSecretRepos

func (f *FakeClient) SetOrgSecretRepos(_ context.Context, org, name string, repoIDs []int64) error

type FileRecord

type FileRecord struct {
	Owner, Repo, Path, Branch, Message string
	Content                            []byte
}

FileRecord records a file creation/update call.

type Installation

type Installation struct {
	ID      int
	AppID   int
	AppSlug string
}

Installation represents an app installation on an org.

type OrgSecretRecord

type OrgSecretRecord struct {
	Org, Name, Value string
	RepoIDs          []int64
}

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.

type WorkflowRun

type WorkflowRun struct {
	ID         int
	Name       string
	Status     string // "queued", "in_progress", "completed"
	Conclusion string // "success", "failure", "cancelled", etc.
	HTMLURL    string
	CreatedAt  string
}

WorkflowRun represents a CI/CD workflow execution.

Directories

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

Jump to

Keyboard shortcuts

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