github

package
v0.0.13 Latest Latest
Warning

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

Go to latest
Published: Jul 1, 2026 License: GPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package github provides functionality to interact with the GitHub API.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Token added in v0.0.5

func Token(ctx context.Context, authMode AuthMode) string

Token resolves a GitHub token for the given auth mode, returning an empty string when none can be obtained. It lets the git package authenticate HTTPS clones and pulls of private repositories with the same credential as the API.

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

func FetchRepos(ctx context.Context, owner string, limit int) ([]Repo, error)

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))
}

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

func FetchReposWithOptions(ctx context.Context, owner string, opts FetchOptions) ([]Repo, error)

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)
	}
}

Jump to

Keyboard shortcuts

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