github

package
v0.62.0 Latest Latest
Warning

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

Go to latest
Published: Mar 13, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package github provides client and data types for the GitHub REST API.

Package github provides client and data types for the GitHub REST API.

Package github provides client and data types for the GitHub REST API.

This package handles all interactions with GitHub's issue tracking system, including fetching, creating, and updating issues. It provides bidirectional mapping between GitHub's data model and Beads' internal types.

Index

Constants

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

	// DefaultTimeout is the default HTTP request timeout.
	DefaultTimeout = 30 * time.Second

	// MaxRetries is the maximum number of retries for rate-limited requests.
	MaxRetries = 3

	// RetryDelay is the base delay between retries (exponential backoff).
	RetryDelay = time.Second

	// MaxPerPage is the maximum number of issues to fetch per page.
	MaxPerPage = 100

	// MaxPages is the maximum number of pages to fetch before stopping.
	// This prevents infinite loops from malformed Link headers.
	MaxPages = 1000
)

API configuration constants.

Variables

View Source
var PriorityMapping = map[string]int{
	"critical": 0,
	"high":     1,
	"medium":   2,
	"low":      3,
	"none":     4,
}

PriorityMapping maps priority label values to beads priority (0-4). This is the single source of truth for priority mappings.

View Source
var StatusMapping = map[string]string{
	"open":        "open",
	"in_progress": "in_progress",
	"blocked":     "blocked",
	"deferred":    "deferred",
	"closed":      "closed",
}

StatusMapping maps status label values to beads status strings. This is the single source of truth for status mappings.

Functions

func BeadsIssueToGitHubFields

func BeadsIssueToGitHubFields(issue *types.Issue, config *MappingConfig) map[string]interface{}

BeadsIssueToGitHubFields converts a beads Issue to GitHub API update fields.

Types

type Client

type Client struct {
	Token      string       // GitHub personal access token
	BaseURL    string       // GitHub API base URL (e.g., "https://api.github.com")
	Owner      string       // Repository owner (user or organization)
	Repo       string       // Repository name
	HTTPClient *http.Client // Optional custom HTTP client
}

Client provides methods to interact with the GitHub REST API.

func NewClient

func NewClient(token, owner, repo string) *Client

NewClient creates a new GitHub client with the given token, owner, and repo.

func (*Client) AddLabels

func (c *Client) AddLabels(ctx context.Context, number int, labels []string) error

AddLabels adds labels to an existing issue.

func (*Client) CreateIssue

func (c *Client) CreateIssue(ctx context.Context, title, body string, labels []string) (*Issue, error)

CreateIssue creates a new issue in GitHub.

func (*Client) FetchIssueByNumber

func (c *Client) FetchIssueByNumber(ctx context.Context, number int) (*Issue, error)

FetchIssueByNumber retrieves a single issue by its repository-scoped number.

func (*Client) FetchIssues

func (c *Client) FetchIssues(ctx context.Context, state string) ([]Issue, error)

FetchIssues retrieves issues from GitHub with optional filtering by state. state can be: "open", "closed", or "all". Filters out pull requests (GitHub's Issues API includes PRs).

func (*Client) FetchIssuesSince

func (c *Client) FetchIssuesSince(ctx context.Context, state string, since time.Time) ([]Issue, error)

FetchIssuesSince retrieves issues from GitHub that have been updated since the given time. This enables incremental sync by only fetching issues modified after the last sync.

func (*Client) GetAuthenticatedUser

func (c *Client) GetAuthenticatedUser(ctx context.Context) (*User, error)

GetAuthenticatedUser returns the authenticated user's information.

func (*Client) ListRepositories

func (c *Client) ListRepositories(ctx context.Context) ([]Repository, error)

ListRepositories retrieves repositories accessible to the authenticated user.

func (*Client) RemoveLabel

func (c *Client) RemoveLabel(ctx context.Context, number int, label string) error

RemoveLabel removes a label from an existing issue.

func (*Client) UpdateIssue

func (c *Client) UpdateIssue(ctx context.Context, number int, updates map[string]interface{}) (*Issue, error)

UpdateIssue updates an existing issue in GitHub.

func (*Client) WithBaseURL

func (c *Client) WithBaseURL(baseURL string) *Client

WithBaseURL returns a new client configured to use a custom API base URL. This is useful for testing with mock servers or GitHub Enterprise instances.

func (*Client) WithHTTPClient

func (c *Client) WithHTTPClient(httpClient *http.Client) *Client

WithHTTPClient returns a new client configured to use the specified HTTP client. This is useful for testing or customizing timeouts and transport settings.

type Conflict

type Conflict struct {
	IssueID           string    // Beads issue ID
	LocalUpdated      time.Time // When the local version was last modified
	GitHubUpdated     time.Time // When the GitHub version was last modified
	GitHubExternalRef string    // URL to the GitHub issue
	GitHubNumber      int       // GitHub issue number (repository-scoped)
	GitHubID          int       // GitHub's global issue ID
}

Conflict represents a conflict between local and GitHub versions. A conflict occurs when both the local and GitHub versions have been modified since the last sync.

type DependencyInfo

type DependencyInfo struct {
	FromGitHubNumber int    // GitHub number of the dependent issue
	ToGitHubNumber   int    // GitHub number of the dependency target
	Type             string // Beads dependency type (blocks, related, parent-child)
}

DependencyInfo represents a dependency to be created after issue import. Stored separately since we need all issues imported before linking dependencies.

type Issue

type Issue struct {
	ID        int        `json:"id"`     // Global issue ID
	Number    int        `json:"number"` // Repository-scoped issue number
	Title     string     `json:"title"`
	Body      string     `json:"body"`
	State     string     `json:"state"` // "open", "closed"
	CreatedAt *time.Time `json:"created_at"`
	UpdatedAt *time.Time `json:"updated_at"`
	ClosedAt  *time.Time `json:"closed_at,omitempty"`
	Labels    []Label    `json:"labels"`
	Assignee  *User      `json:"assignee,omitempty"`
	Assignees []User     `json:"assignees,omitempty"`
	User      *User      `json:"user,omitempty"` // Issue author
	Milestone *Milestone `json:"milestone,omitempty"`
	HTMLURL   string     `json:"html_url"`
	Locked    bool       `json:"locked"`

	// PullRequest is non-nil if this issue is actually a pull request.
	// Used to filter PRs out of issue listings.
	PullRequest *PullRequestRef `json:"pull_request,omitempty"`
}

Issue represents an issue from the GitHub API.

func (*Issue) IsPullRequest

func (i *Issue) IsPullRequest() bool

IsPullRequest returns true if this issue is actually a pull request.

func (*Issue) LabelNames

func (i *Issue) LabelNames() []string

LabelNames returns the names of all labels on this issue.

type IssueConversion

type IssueConversion struct {
	Issue        *types.Issue
	Dependencies []DependencyInfo
}

IssueConversion holds the result of converting a GitHub issue to Beads. It includes the issue and any dependencies that should be created.

func GitHubIssueToBeads

func GitHubIssueToBeads(gh *Issue, config *MappingConfig) *IssueConversion

GitHubIssueToBeads converts a GitHub Issue to a beads Issue.

type Label

type Label struct {
	ID          int    `json:"id"`
	Name        string `json:"name"`
	Color       string `json:"color,omitempty"`
	Description string `json:"description,omitempty"`
	Default     bool   `json:"default,omitempty"`
}

Label represents a GitHub label.

type MappingConfig

type MappingConfig struct {
	PriorityMap  map[string]int    // priority label value -> beads priority (0-4)
	StateMap     map[string]string // GitHub state -> beads status
	LabelTypeMap map[string]string // type label value -> beads issue type
}

MappingConfig configures how GitHub fields map to beads fields.

func DefaultMappingConfig

func DefaultMappingConfig() *MappingConfig

DefaultMappingConfig returns the default mapping configuration. Uses exported mapping constants from types.go as the single source of truth.

type Milestone

type Milestone struct {
	ID          int        `json:"id"`
	Number      int        `json:"number"`
	Title       string     `json:"title"`
	Description string     `json:"description,omitempty"`
	State       string     `json:"state"` // "open", "closed"
	DueOn       *time.Time `json:"due_on,omitempty"`
	CreatedAt   *time.Time `json:"created_at,omitempty"`
	UpdatedAt   *time.Time `json:"updated_at,omitempty"`
	HTMLURL     string     `json:"html_url,omitempty"`
}

Milestone represents a GitHub milestone.

type PullRequestRef

type PullRequestRef struct {
	URL string `json:"url,omitempty"`
}

PullRequestRef is a minimal reference indicating an issue is a PR.

type PullStats

type PullStats struct {
	Created     int
	Updated     int
	Skipped     int
	Incremental bool     // Whether this was an incremental sync
	SyncedSince string   // Timestamp we synced since (if incremental)
	Warnings    []string // Non-fatal warnings encountered during pull
}

PullStats tracks pull operation statistics.

type PushStats

type PushStats struct {
	Created int
	Updated int
	Skipped int
	Errors  int
}

PushStats tracks push operation statistics.

type Repository

type Repository struct {
	ID            int    `json:"id"`
	Name          string `json:"name"`
	FullName      string `json:"full_name"` // "owner/repo"
	Description   string `json:"description,omitempty"`
	HTMLURL       string `json:"html_url"`
	DefaultBranch string `json:"default_branch,omitempty"`
	Private       bool   `json:"private"`
	Owner         *User  `json:"owner,omitempty"`
}

Repository represents a GitHub repository.

type SyncResult

type SyncResult struct {
	Success  bool      `json:"success"`
	Stats    SyncStats `json:"stats"`
	LastSync string    `json:"last_sync,omitempty"`
	Error    string    `json:"error,omitempty"`
	Warnings []string  `json:"warnings,omitempty"`
}

SyncResult represents the result of a GitHub sync operation.

type SyncStats

type SyncStats struct {
	Pulled    int `json:"pulled"`
	Pushed    int `json:"pushed"`
	Created   int `json:"created"`
	Updated   int `json:"updated"`
	Skipped   int `json:"skipped"`
	Errors    int `json:"errors"`
	Conflicts int `json:"conflicts"`
}

SyncStats tracks statistics for a GitHub sync operation.

type Tracker

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

Tracker implements tracker.IssueTracker for GitHub.

func (*Tracker) BuildExternalRef

func (t *Tracker) BuildExternalRef(issue *tracker.TrackerIssue) string

func (*Tracker) Close

func (t *Tracker) Close() error

func (*Tracker) ConfigPrefix

func (t *Tracker) ConfigPrefix() string

func (*Tracker) CreateIssue

func (t *Tracker) CreateIssue(ctx context.Context, issue *types.Issue) (*tracker.TrackerIssue, error)

func (*Tracker) DisplayName

func (t *Tracker) DisplayName() string

func (*Tracker) ExtractIdentifier

func (t *Tracker) ExtractIdentifier(ref string) string

func (*Tracker) FetchIssue

func (t *Tracker) FetchIssue(ctx context.Context, identifier string) (*tracker.TrackerIssue, error)

func (*Tracker) FetchIssues

func (t *Tracker) FetchIssues(ctx context.Context, opts tracker.FetchOptions) ([]tracker.TrackerIssue, error)

func (*Tracker) FieldMapper

func (t *Tracker) FieldMapper() tracker.FieldMapper

func (*Tracker) Init

func (t *Tracker) Init(ctx context.Context, store storage.Storage) error

func (*Tracker) IsExternalRef

func (t *Tracker) IsExternalRef(ref string) bool

func (*Tracker) Name

func (t *Tracker) Name() string

func (*Tracker) UpdateIssue

func (t *Tracker) UpdateIssue(ctx context.Context, externalID string, issue *types.Issue) (*tracker.TrackerIssue, error)

func (*Tracker) Validate

func (t *Tracker) Validate() error

type User

type User struct {
	ID        int    `json:"id"`
	Login     string `json:"login"`
	Name      string `json:"name,omitempty"`
	Email     string `json:"email,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
	HTMLURL   string `json:"html_url,omitempty"`
	Type      string `json:"type,omitempty"` // "User", "Organization", "Bot"
}

User represents a GitHub user.

Jump to

Keyboard shortcuts

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