gh

package
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Dec 23, 2025 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	StatusQueued     = "queued"
	StatusInProgress = "in_progress"
	StatusCompleted  = "completed"
)

RunStatus constants

View Source 
const (
	ConclusionSuccess        = "success"
	ConclusionFailure        = "failure"
	ConclusionCancelled      = "cancelled"
	ConclusionSkipped        = "skipped"
	ConclusionTimedOut       = "timed_out"
	ConclusionActionRequired = "action_required"
	ConclusionNeutral        = "neutral"
)

Conclusion constants

Variables

View Source 
var (
	// ErrNotAuthenticated is returned when GitHub authentication fails
	ErrNotAuthenticated = errors.New("not authenticated to GitHub")

	// ErrRepoNotFound is returned when the repository is not found
	ErrRepoNotFound = errors.New("repository not found")

	// ErrRateLimited is returned when GitHub API rate limit is exceeded
	ErrRateLimited = errors.New("GitHub API rate limit exceeded")

	// ErrNoRuns is returned when no workflow runs are found
	ErrNoRuns = errors.New("no workflow runs found for this branch")
)

Functions

func CheckHTTPError 

func CheckHTTPError(err error, statusCode int) bool

CheckHTTPError checks if an error is an HTTP error with the given status code

func IsHTTPError 

func IsHTTPError(err error) bool

IsHTTPError checks if the error is an HTTP error

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable determines if an error should trigger a retry

func RetryWithBackoff 

func RetryWithBackoff(fn func() error, config RetryConfig) error

RetryWithBackoff executes a function with exponential backoff retry logic

Types

type Artifact 

type Artifact struct {
	ID                 int64     `json:"id"`
	NodeID             string    `json:"node_id"`
	Name               string    `json:"name"`
	SizeInBytes        int64     `json:"size_in_bytes"`
	URL                string    `json:"url"`
	ArchiveDownloadURL string    `json:"archive_download_url"`
	Expired            bool      `json:"expired"`
	CreatedAt          time.Time `json:"created_at"`
	UpdatedAt          time.Time `json:"updated_at"`
}

Artifact represents a GitHub Actions artifact

type ArtifactsResponse 

type ArtifactsResponse struct {
	TotalCount int        `json:"total_count"`
	Artifacts  []Artifact `json:"artifacts"`
}

ArtifactsResponse is the API response for listing artifacts

type AuthError 

type AuthError struct {
	Err error
}

AuthError wraps authentication-related errors with helpful messages

func (*AuthError) Error 

func (e *AuthError) Error() string

func (*AuthError) Unwrap 

func (e *AuthError) Unwrap() error

type Branch 

type Branch struct {
	Name      string `json:"name"`
	Commit    Commit `json:"commit"`
	Protected bool   `json:"protected"`
}

Branch represents a git branch

type BranchesResponse 

type BranchesResponse []Branch

BranchesResponse is the API response for listing branches

type Client 

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

Client wraps the GitHub REST API client

func NewClient 

func NewClient() (*Client, error)

NewClient creates a new GitHub API client. It tries to use gh CLI authentication first, then falls back to GITHUB_TOKEN.

func (*Client) CancelWorkflow 

func (c *Client) CancelWorkflow(owner, repo string, runID int64) error

CancelWorkflow cancels the specified workflow run

func (*Client) DispatchWorkflow 

func (c *Client) DispatchWorkflow(owner, repo, workflowFile, ref string) error

DispatchWorkflow triggers a workflow_dispatch event

func (*Client) DownloadArtifact 

func (c *Client) DownloadArtifact(owner, repo string, artifactID int64, filename string) error

DownloadArtifact downloads an artifact to the current directory

func (*Client) FetchBranch 

func (c *Client) FetchBranch(owner, repo, branch string) (*Branch, error)

FetchBranch fetches information about a specific branch.

func (*Client) FetchBranches 

func (c *Client) FetchBranches(owner, repo string) ([]Branch, error)

FetchBranches fetches all branches for a repository.

func (*Client) FetchJobDetails 

func (c *Client) FetchJobDetails(owner, repo string, jobID int64) (*Job, error)

FetchJobDetails fetches detailed information for a specific job including steps.

func (*Client) FetchJobLogs 

func (c *Client) FetchJobLogs(owner, repo string, jobID int64) (string, error)

FetchJobLogs fetches and extracts the logs for a specific job. Returns the combined log text from all log files in the ZIP.

func (*Client) FetchJobLogsStructured 

func (c *Client) FetchJobLogsStructured(owner, repo string, jobID int64) (*ParsedLogs, error)

FetchJobLogsStructured fetches logs with step-level structure (v0.6)

func (*Client) FetchJobs 

func (c *Client) FetchJobs(owner, repo string, runID int64) ([]Job, error)

FetchJobs fetches all jobs for a workflow run.

func (*Client) FetchLatestRun 

func (c *Client) FetchLatestRun(owner, repo, branch string) (*WorkflowRun, error)

FetchLatestRun fetches the most recent workflow run for a branch. Returns ErrNoRuns if no runs are found.

func (*Client) FetchRun 

func (c *Client) FetchRun(owner, repo string, runID int64) (*WorkflowRun, error)

FetchRun fetches a specific workflow run by ID.

func (*Client) FetchWorkflowArtifacts 

func (c *Client) FetchWorkflowArtifacts(owner, repo string, runID int64) ([]Artifact, error)

FetchWorkflowArtifacts fetches artifacts for a specific workflow run

func (*Client) FetchWorkflowContent 

func (c *Client) FetchWorkflowContent(owner, repo, path string) (string, error)

FetchWorkflowContent fetches the content of a workflow file

func (*Client) FetchWorkflowRuns 

func (c *Client) FetchWorkflowRuns(owner, repo, branch, status string, page, perPage int) ([]WorkflowRun, error)

FetchWorkflowRuns fetches workflow runs with pagination and optional filtering.

func (*Client) Get 

func (c *Client) Get(path string, response interface{}) error

Get performs a GET request to the GitHub API with retry logic

func (*Client) GetRepository 

func (c *Client) GetRepository(owner, repo string) (*Repository, error)

GetRepository fetches repository information from GitHub API

func (*Client) Post 

func (c *Client) Post(path string, payload interface{}) error

Post performs a POST request to the GitHub API with retry logic

func (*Client) RerunWorkflow 

func (c *Client) RerunWorkflow(owner, repo string, runID int64) error

RerunWorkflow triggers a rerun of the specified workflow run

type Commit 

type Commit struct {
	SHA string `json:"sha"`
	URL string `json:"url"`
}

Commit represents a commit (simplified for branch listing)

type Content 

type Content struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	SHA         string `json:"sha"`
	Size        int    `json:"size"`
	URL         string `json:"url"`
	HTMLURL     string `json:"html_url"`
	GitURL      string `json:"git_url"`
	DownloadURL string `json:"download_url"`
	Type        string `json:"type"`     // "file" or "dir"
	Content     string `json:"content"`  // base64 encoded content (only for files)
	Encoding    string `json:"encoding"` // "base64" for files
}

Content represents a file or directory from the GitHub Contents API

type Job 

type Job struct {
	ID          int64      `json:"id"`
	Name        string     `json:"name"`
	Status      string     `json:"status"`     // queued, in_progress, completed
	Conclusion  *string    `json:"conclusion"` // success, failure, cancelled, skipped
	StartedAt   *time.Time `json:"started_at"`
	CompletedAt *time.Time `json:"completed_at"`
	HTMLURL     string     `json:"html_url"`
	RunnerName  string     `json:"runner_name"`
	Steps       []JobStep  `json:"steps"`
}

Job represents a job within a workflow run

func (*Job) Duration 

func (j *Job) Duration() time.Duration

Duration returns the duration of a completed job

func (*Job) IsCompleted 

func (j *Job) IsCompleted() bool

IsCompleted returns true if the job has completed

type JobStep 

type JobStep struct {
	Number      int        `json:"number"`
	Name        string     `json:"name"`
	Status      string     `json:"status"`     // pending, in_progress, completed
	Conclusion  *string    `json:"conclusion"` // success, failure, cancelled, skipped
	StartedAt   *time.Time `json:"started_at"`
	CompletedAt *time.Time `json:"completed_at"`
}

JobStep represents a step within a job

type JobsResponse 

type JobsResponse struct {
	TotalCount int   `json:"total_count"`
	Jobs       []Job `json:"jobs"`
}

JobsResponse is the API response for listing jobs

type NotFoundError 

type NotFoundError struct {
	Resource string
	Err      error
}

NotFoundError wraps 404 errors

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

func (*NotFoundError) Unwrap 

func (e *NotFoundError) Unwrap() error

type ParsedLogs 

type ParsedLogs struct {
	Steps      []StepLog         // Individual step logs in order
	StepsByKey map[string]string // Quick lookup by "number_name" key
	Combined   string            // Full combined log content (for backward compat)
}

ParsedLogs represents structured log data with step-level granularity

func (*ParsedLogs) FilteredContent 

func (p *ParsedLogs) FilteredContent(stepNumbers []int) string

FilteredContent returns log content filtered to specific step numbers

func (*ParsedLogs) GetStep 

func (p *ParsedLogs) GetStep(number int) string

GetStep returns the log content for a specific step by number

func (*ParsedLogs) GetStepByName 

func (p *ParsedLogs) GetStepByName(name string) string

GetStepByName returns the log content for a step by name (partial match)

type RateLimitError 

type RateLimitError struct {
	Err error
}

RateLimitError wraps rate limit errors

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

func (*RateLimitError) Unwrap 

func (e *RateLimitError) Unwrap() error

type Repository 

type Repository struct {
	Name          string `json:"name"`
	FullName      string `json:"full_name"`
	DefaultBranch string `json:"default_branch"`
}

Repository represents a GitHub repository

type RetryConfig 

type RetryConfig struct {
	MaxRetries int
	BaseDelay  time.Duration
	MaxDelay   time.Duration
}

RetryConfig holds retry configuration

func DefaultRetryConfig 

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns sensible defaults for API retries

type RetryableError 

type RetryableError struct {
	Err       error
	Retryable bool
}

RetryableError represents an error that can be retried

func (RetryableError) Error 

func (e RetryableError) Error() string

func (RetryableError) Unwrap 

func (e RetryableError) Unwrap() error

type SourcedRun 

type SourcedRun struct {
	Owner string       // Repository owner
	Repo  string       // Repository name
	Run   *WorkflowRun // The actual workflow run
}

SourcedRun wraps a WorkflowRun with its source repository info (v0.8)

func (*SourcedRun) RepoSlug 

func (s *SourcedRun) RepoSlug() string

RepoSlug returns "owner/repo" format

type StepLog 

type StepLog struct {
	Number  int    // Step number (e.g., 1, 2, 3)
	Name    string // Step name (e.g., "Checkout", "Build", "Test")
	Content string // The actual log content for this step
}

StepLog represents logs for a single step within a job

type User 

type User struct {
	Login string `json:"login"`
}

User represents a GitHub user

type WorkflowRun 

type WorkflowRun struct {
	ID         int64     `json:"id"`
	Name       string    `json:"name"`
	Path       string    `json:"path"` // workflow file path, e.g. ".github/workflows/ci.yml"
	RunNumber  int       `json:"run_number"`
	Status     string    `json:"status"`     // queued, in_progress, completed
	Conclusion *string   `json:"conclusion"` // success, failure, cancelled, skipped, timed_out, action_required
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	HTMLURL    string    `json:"html_url"`
	Event      string    `json:"event"` // push, pull_request, workflow_dispatch, etc.
	HeadBranch string    `json:"head_branch"`
	Actor      *User     `json:"actor"`
}

WorkflowRun represents a GitHub Actions workflow run

func (*WorkflowRun) ActorLogin 

func (r *WorkflowRun) ActorLogin() string

ActorLogin returns the login of the actor who triggered the run

func (*WorkflowRun) IsCompleted 

func (r *WorkflowRun) IsCompleted() bool

IsCompleted returns true if the run has completed

func (*WorkflowRun) IsFailure 

func (r *WorkflowRun) IsFailure() bool

IsFailure returns true if the run failed

func (*WorkflowRun) IsSuccess 

func (r *WorkflowRun) IsSuccess() bool

IsSuccess returns true if the run completed successfully

type WorkflowRunsResponse 

type WorkflowRunsResponse struct {
	TotalCount   int           `json:"total_count"`
	WorkflowRuns []WorkflowRun `json:"workflow_runs"`
}

WorkflowRunsResponse is the API response for listing workflow runs

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.