Documentation
¶
Overview ¶
Package github provides functionality to interact with the GitHub API.
Index ¶
- func Token(ctx context.Context, authMode AuthMode) string
- type AuthMode
- type FetchOptions
- type Repo
- func FetchRepos(ctx context.Context, owner string, limit int) ([]Repo, error)
- func FetchReposWithClient(ctx context.Context, client *gh.Client, owner string, limit int) ([]Repo, error)
- func FetchReposWithClientOptions(ctx context.Context, client *gh.Client, owner string, opts FetchOptions) ([]Repo, error)
- func FetchReposWithOptions(ctx context.Context, owner string, opts FetchOptions) ([]Repo, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type AuthMode ¶ added in v0.0.3
type AuthMode string
AuthMode controls how GitHub API credentials are resolved.
const ( // AuthModeAuto resolves credentials from the environment first, then the gh CLI. AuthModeAuto AuthMode = "auto" // AuthModeToken resolves credentials only from environment variables. AuthModeToken AuthMode = "token" // AuthModeGH resolves credentials only via the gh CLI (`gh auth token`). AuthModeGH AuthMode = "gh" )
type FetchOptions ¶ added in v0.0.3
type FetchOptions struct {
// Limit caps the number of repositories returned; 0 means no limit.
Limit int
// Visibility filters repositories by visibility ("all", "public", or "private").
Visibility string
// IncludeForks includes forked repositories when true.
IncludeForks bool
// IncludeArchived includes archived repositories when true.
IncludeArchived bool
// IncludeLanguages, when non-empty, keeps only repositories matching these languages.
IncludeLanguages []string
// ExcludeLanguages removes repositories matching these languages.
ExcludeLanguages []string
// AuthMode selects how the GitHub token is resolved.
AuthMode AuthMode
// Type filters repositories by specific category (e.g. "sources", "forks", "archived", "mirrors", etc.).
Type string
// Sort specifies how the returned repositories list should be ordered.
Sort string
// RetryMax is the maximum number of retry attempts for transient failures.
RetryMax int
// RetryMinBackoff is the minimum delay between retry attempts.
RetryMinBackoff time.Duration
// RetryMaxBackoff is the maximum delay between retry attempts.
RetryMaxBackoff time.Duration
}
FetchOptions configures repository fetch behavior.
type Repo ¶
type Repo struct {
// Name is the repository name (without the owner prefix).
Name string
// Language is the primary programming language, or "Other" when unknown.
Language string
// Visibility is the normalized visibility, either "Public" or "Private".
Visibility string
// DefaultBranch is the repository's default branch name.
DefaultBranch string
// CloneURL is the HTTPS clone URL for the repository.
CloneURL string
// SSHURL is the SSH clone URL for the repository.
SSHURL string
// Fork reports whether the repository is a fork.
Fork bool
// Archived reports whether the repository is archived.
Archived bool
// PushedAt is the timestamp of the last push to any branch. The engine
// compares this against the cached value in <repo>/.corral-state.json to
// skip a `git pull` when nothing has changed upstream.
PushedAt time.Time
// Stars reports the stargazers count for the repository.
Stars int
// IsTemplate reports whether the repository is a template.
IsTemplate bool
// IsMirror reports whether the repository is a mirror.
IsMirror bool
// CanBeSponsored reports whether the repository has sponsorships enabled.
CanBeSponsored bool
}
Repo represents a simplified repository structure returned by the GitHub API.
func FetchRepos ¶
FetchRepos retrieves repositories for a given owner up to the specified limit.
Example ¶
ExampleFetchRepos demonstrates the simplest fetch: every repository for an owner, resolving credentials automatically from the environment or gh CLI.
package main
import (
"context"
"fmt"
"log"
"github.com/sebastienrousseau/corral/internal/github"
)
func main() {
ctx := context.Background()
repos, err := github.FetchRepos(ctx, "sebastienrousseau", 1000)
if err != nil {
log.Fatal(err)
}
fmt.Printf("fetched %d repositories\n", len(repos))
}
Output:
func FetchReposWithClient ¶
func FetchReposWithClient(ctx context.Context, client *gh.Client, owner string, limit int) ([]Repo, error)
FetchReposWithClient allows injecting a GitHub client for retrieving repositories. This is primarily exposed for testing purposes.
func FetchReposWithClientOptions ¶ added in v0.0.3
func FetchReposWithClientOptions(ctx context.Context, client *gh.Client, owner string, opts FetchOptions) ([]Repo, error)
FetchReposWithClientOptions allows injecting a GitHub client and advanced filtering.
func FetchReposWithOptions ¶ added in v0.0.3
FetchReposWithOptions retrieves repositories with explicit fetch options.
Example ¶
ExampleFetchReposWithOptions demonstrates fetching only private, non-fork, non-archived Go repositories using GitHub CLI credentials, with bounded exponential-backoff retries on transient API failures.
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/sebastienrousseau/corral/internal/github"
)
func main() {
ctx := context.Background()
repos, err := github.FetchReposWithOptions(ctx, "sebastienrousseau", github.FetchOptions{
Limit: 100,
Visibility: "private",
IncludeForks: false,
IncludeArchived: false,
IncludeLanguages: []string{"go"},
ExcludeLanguages: []string{"makefile"},
AuthMode: github.AuthModeGH,
RetryMax: 4,
RetryMinBackoff: 500 * time.Millisecond,
RetryMaxBackoff: 8 * time.Second,
})
if err != nil {
log.Fatal(err)
}
for _, r := range repos {
fmt.Printf("%s (%s, %s)\n", r.Name, r.Visibility, r.Language)
}
}
Output: