githubclient

Documentation

Index

• Constants
• Variables
• type Client
  • func NewClient(token string) *Client
  • func NewClientWithBaseURL(token, baseURL string) *Client
  • func (c *Client) AllowPullRequestWrites()
  • func (c *Client) GetPullRequestDiff(ctx context.Context, owner, repo string, number int) (*Diff, error)
  • func (c *Client) GetRepositoryFile(ctx context.Context, owner, repo, path, ref string) ([]byte, bool, error)
  • func (c *Client) HasWritePermission(ctx context.Context, owner, repo string) (bool, error)
  • func (c *Client) ListChangedFiles(ctx context.Context, owner, repo string, number int) ([]string, error)
  • func (c *Client) PostIssueComment(ctx context.Context, owner, repo string, number int, body string) error
  • func (c *Client) PostPullRequestReview(ctx context.Context, owner, repo string, number int, review PullRequestReview, ...) error
  • func (c *Client) PostReviewComment(ctx context.Context, owner, repo string, number int, comment ReviewComment, ...) error
  • func (c *Client) SetStatus(ctx context.Context, owner, repo, sha string, status CommitStatus) error
• type CommitStatus
• type Diff
• type DiffFile
• type DiffHunk
• type PullRequestReview
• type ReviewComment
• type ReviewLineComment

Constants

const (
	// DefaultBaseURL is the GitHub API base URL
	DefaultBaseURL = "https://api.github.com"

	// UserAgent identifies AurumCode
	UserAgent = "AurumCode/1.0"

	// MaxRetries is the maximum number of retry attempts
	MaxRetries = 3

	// InitialBackoff is the initial backoff duration
	InitialBackoff = 1 * time.Second
)

Variables

var ErrNoWritePermission = errors.New("token lacks write permission on repository")

ErrNoWritePermission is returned by the publishing methods (PostIssueComment, PostReviewComment, PostPullRequestReview, SetStatus) when the client is using its repository-role preflight and the authenticated token does not carry write permission on the target repository.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a GitHub API client with retry and rate-limit handling

func NewClient

func NewClient(token string) *Client

NewClient creates a new GitHub API client

func NewClientWithBaseURL

func NewClientWithBaseURL(token, baseURL string) *Client

NewClientWithBaseURL creates a client with a custom base URL (for testing)

func (*Client) AllowPullRequestWrites

func (c *Client) AllowPullRequestWrites()

AllowPullRequestWrites selects the permission model used by the PR review path. The GitHub API enforces the actual pull-request/status scope on the POST; the repository-role preflight is intentionally skipped because it describes push/maintain/admin access, not a workflow token's endpoint scope. This keeps comments limited to pull-requests:write and statuses limited to statuses:write.

func (*Client) GetPullRequestDiff

func (c *Client) GetPullRequestDiff(ctx context.Context, owner, repo string, number int) (*Diff, error)

GetPullRequestDiff retrieves the diff for a pull request with ETag caching

func (*Client) GetRepositoryFile

func (c *Client) GetRepositoryFile(ctx context.Context, owner, repo, path, ref string) ([]byte, bool, error)

GetRepositoryFile reads a small text file from a repository ref without checking out or executing repository code. The contents endpoint returns base64 JSON, which keeps this path usable for a pull request workflow whose workspace contains only the trusted AurumCode checkout. A missing file is a normal zero-config result (found=false); malformed or oversized content is a loud error.

func (*Client) HasWritePermission

func (c *Client) HasWritePermission(ctx context.Context, owner, repo string) (bool, error)

HasWritePermission reports whether the authenticated token can write to owner/repo, from the "permissions" object of GET /repos/{owner}/{repo}. A repository answer without a permissions object counts as no write permission: the check fails closed. Verdicts are cached per owner/repo for the lifetime of the client.

func (*Client) ListChangedFiles

func (c *Client) ListChangedFiles(ctx context.Context, owner, repo string, number int) ([]string, error)

ListChangedFiles retrieves the list of changed files in a pull request with pagination

func (*Client) PostIssueComment

func (c *Client) PostIssueComment(ctx context.Context, owner, repo string, number int, body string) error

PostIssueComment posts a general comment on a pull request (not tied to a specific line). It refuses with ErrNoWritePermission when the token cannot write to the repository.

func (*Client) PostPullRequestReview

func (c *Client) PostPullRequestReview(ctx context.Context, owner, repo string, number int, review PullRequestReview, idempotencyKey string) error

PostPullRequestReview submits one formal review to a pull request. The review may contain zero or more inline comments and is shown by GitHub as a single COMMENT, APPROVE, or REQUEST_CHANGES review in the PR's review UI.

func (*Client) PostReviewComment

func (c *Client) PostReviewComment(ctx context.Context, owner, repo string, number int, comment ReviewComment, idempotencyKey string) error

PostReviewComment posts a review comment on a pull request with idempotency. It refuses with ErrNoWritePermission when the token cannot write to the repository.

func (*Client) SetStatus

func (c *Client) SetStatus(ctx context.Context, owner, repo, sha string, status CommitStatus) error

SetStatus sets the commit status for a specific SHA

type CommitStatus

type CommitStatus struct {
	State       string `json:"state"`                 // "pending", "success", "error", or "failure"
	TargetURL   string `json:"target_url,omitempty"`  // Optional URL
	Description string `json:"description,omitempty"` // Short description
	Context     string `json:"context"`               // Label to differentiate this status
}

CommitStatus represents a commit status update

type Diff

type Diff struct {
	Files []DiffFile `json:"files" yaml:"files"`
}

Diff represents the complete parsed diff

type DiffFile

type DiffFile struct {
	Path  string     `json:"path" yaml:"path"`
	Lang  string     `json:"lang" yaml:"lang"`
	Hunks []DiffHunk `json:"hunks" yaml:"hunks"`
}

DiffFile represents a single file in a diff

type DiffHunk

type DiffHunk struct {
	OldStart int      `json:"old_start" yaml:"old_start"`
	OldLines int      `json:"old_lines" yaml:"old_lines"`
	NewStart int      `json:"new_start" yaml:"new_start"`
	NewLines int      `json:"new_lines" yaml:"new_lines"`
	Lines    []string `json:"lines" yaml:"lines"`
}

DiffHunk represents a single hunk within a file diff

type PullRequestReview

type PullRequestReview struct {
	Body     string              `json:"body"`
	Event    string              `json:"event"`
	CommitID string              `json:"commit_id,omitempty"`
	Comments []ReviewLineComment `json:"comments,omitempty"`
}

PullRequestReview is the formal review submitted to GitHub's pull request review endpoint. Event is one of COMMENT, APPROVE, or REQUEST_CHANGES.

type ReviewComment

type ReviewComment struct {
	Body     string `json:"body"`
	CommitID string `json:"commit_id"`
	Path     string `json:"path"`
	Line     int    `json:"line,omitempty"`     // For single-line comments
	Position int    `json:"position,omitempty"` // Alternative to Line (deprecated by GitHub)
}

ReviewComment represents a review comment to be posted

type ReviewLineComment

type ReviewLineComment struct {
	Body      string `json:"body"`
	Path      string `json:"path"`
	Line      int    `json:"line,omitempty"`
	Side      string `json:"side,omitempty"`
	StartLine int    `json:"start_line,omitempty"`
	StartSide string `json:"start_side,omitempty"`
}

ReviewLineComment is an optional inline comment included in a formal pull request review. Its commit is supplied once by PullRequestReview.CommitID, as required by GitHub's create-review API.