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
- Variables
- func BeadsIssueToGitHubFields(issue *types.Issue, config *MappingConfig) map[string]interface{}
- type Client
- func (c *Client) AddLabels(ctx context.Context, number int, labels []string) error
- func (c *Client) CreateIssue(ctx context.Context, title, body string, labels []string) (*Issue, error)
- func (c *Client) FetchIssueByNumber(ctx context.Context, number int) (*Issue, error)
- func (c *Client) FetchIssues(ctx context.Context, state string) ([]Issue, error)
- func (c *Client) FetchIssuesSince(ctx context.Context, state string, since time.Time) ([]Issue, error)
- func (c *Client) GetAuthenticatedUser(ctx context.Context) (*User, error)
- func (c *Client) ListRepositories(ctx context.Context) ([]Repository, error)
- func (c *Client) RemoveLabel(ctx context.Context, number int, label string) error
- func (c *Client) UpdateIssue(ctx context.Context, number int, updates map[string]interface{}) (*Issue, error)
- func (c *Client) WithBaseURL(baseURL string) *Client
- func (c *Client) WithHTTPClient(httpClient *http.Client) *Client
- type Conflict
- type DependencyInfo
- type Issue
- type IssueConversion
- type Label
- type MappingConfig
- type Milestone
- type PullRequestRef
- type PullStats
- type PushStats
- type Repository
- type SyncResult
- type SyncStats
- type Tracker
- func (t *Tracker) BuildExternalRef(issue *tracker.TrackerIssue) string
- func (t *Tracker) Close() error
- func (t *Tracker) ConfigPrefix() string
- func (t *Tracker) CreateIssue(ctx context.Context, issue *types.Issue) (*tracker.TrackerIssue, error)
- func (t *Tracker) DisplayName() string
- func (t *Tracker) ExtractIdentifier(ref string) string
- func (t *Tracker) FetchIssue(ctx context.Context, identifier string) (*tracker.TrackerIssue, error)
- func (t *Tracker) FetchIssues(ctx context.Context, opts tracker.FetchOptions) ([]tracker.TrackerIssue, error)
- func (t *Tracker) FieldMapper() tracker.FieldMapper
- func (t *Tracker) Init(ctx context.Context, store storage.Storage) error
- func (t *Tracker) IsExternalRef(ref string) bool
- func (t *Tracker) Name() string
- func (t *Tracker) UpdateIssue(ctx context.Context, externalID string, issue *types.Issue) (*tracker.TrackerIssue, error)
- func (t *Tracker) Validate() error
- type User
Constants ¶
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 ¶
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.
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 (*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 ¶
FetchIssueByNumber retrieves a single issue by its repository-scoped number.
func (*Client) FetchIssues ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
IsPullRequest returns true if this issue is actually a pull request.
func (*Issue) LabelNames ¶
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 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) ConfigPrefix ¶
func (*Tracker) CreateIssue ¶
func (*Tracker) DisplayName ¶
func (*Tracker) ExtractIdentifier ¶
func (*Tracker) FetchIssue ¶
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) IsExternalRef ¶
func (*Tracker) UpdateIssue ¶
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.