README
¶
forge-github
GitHub provider for forge — releases, device-flow login and SSH-key upload
Part of the phpboyscout Go toolkit. Full documentation lives on the core module's site: forge.go.phpboyscout.uk
Implements the forge.Provider
release contract for GitHub, using
go-github, plus the optional
Authenticator
(OAuth device-flow login) and
KeyManager
(SSH-key upload) capabilities. Works against github.com and GitHub Enterprise.
Capabilities
| Capability | Interface | Notes |
|---|---|---|
| Releases | forge.Provider |
list/get/download releases + checksum/signature |
| Interactive login | forge.Authenticator |
OAuth device flow; surfaces the code via a forge.Prompter (the CLI renders it), needs auth.client_id or GITHUB_CLIENT_ID |
| SSH-key upload | forge.KeyManager |
registers a public key on the account |
A caller type-asserts for a capability and, on a miss (or forge.ErrNotSupported),
falls back — e.g. manual token entry when no client ID is configured. Presentation
stays in the CLI: this adapter speaks only the OAuth protocol and surfaces the device
code; the Prompter decides whether to open a browser.
GitHub's remaining wider API — pull requests, repository creation, file contents — is not here. It is parked in the forge module's provider-contract-widening spec, to be added across every provider in lockstep when a concrete consumer needs it — never letting one forge acquire capabilities the others lack, which is the disparity backend agnosticism exists to prevent.
Use it
import (
"gitlab.com/phpboyscout/go/forge"
_ "gitlab.com/phpboyscout/go/forge-github"
)
factory, err := forge.Lookup("github")
provider, err := factory(source, cfg)
go get gitlab.com/phpboyscout/go/forge-github
Configuration
| Key | Purpose |
|---|---|
github.auth.env |
Name of an environment variable holding the token |
github.auth.keychain |
OS keychain reference, service/account |
github.auth.value |
Literal token — weakest tier, avoid in committed config |
github.auth.client_id |
OAuth app client ID for device-flow login (else GITHUB_CLIENT_ID) |
github.url.api |
Override the API endpoint |
github.url.upload |
Override the asset-upload endpoint |
GITHUB_TOKEN |
Well-known fallback |
For GitHub Enterprise, set ReleaseSource.Host and the API and upload endpoints
are derived (/api/v3/ and /api/uploads/). Setting url.api alone still
derives a matching upload endpoint, so assets never target the wrong host.
A token is optional — public repositories resolve unauthenticated.
Documentation
Guides, the provider contract, and how to author your own: forge.go.phpboyscout.uk.
API reference: pkg.go.dev.
License
See LICENSE.
Documentation
¶
Overview ¶
Package github implements the VCS release provider and API client for GitHub repositories, supporting both public and token-authenticated access. It provides repository management, pull requests, release listing, asset downloads, and file retrieval through a testable [GitHubClient] interface. Client construction uses package-owned [ClientSettings]; GTB config integration lives in [ClientSettingsFromConfig].
Index ¶
- Constants
- func NewReleaseProvider(settings Settings) (forge.Provider, error)
- type GitHubReleaseProvider
- func (p *GitHubReleaseProvider) DownloadReleaseAsset(ctx context.Context, owner, repo string, asset forge.ReleaseAsset) (io.ReadCloser, string, error)
- func (p *GitHubReleaseProvider) GetLatestRelease(ctx context.Context, owner, repo string) (forge.Release, error)
- func (p *GitHubReleaseProvider) GetReleaseByTag(ctx context.Context, owner, repo, tag string) (forge.Release, error)
- func (p *GitHubReleaseProvider) ListReleases(ctx context.Context, owner, repo string, limit int) ([]forge.Release, error)
- func (p *GitHubReleaseProvider) Login(ctx context.Context, prompter forge.Prompter) (string, error)
- func (p *GitHubReleaseProvider) UploadKey(ctx context.Context, name string, publicKey []byte) error
- type Settings
Constants ¶
const DefaultClientIDEnv = "GITHUB_CLIENT_ID"
DefaultClientIDEnv is the well-known environment variable consulted for the OAuth app client ID that the interactive device-flow login ([Authenticator]) requires, when Settings.ClientID is empty.
const DefaultTokenEnv = "GITHUB_TOKEN"
DefaultTokenEnv is the well-known environment variable consulted last when resolving a credential. See forge.ResolveToken.
The suppression below is a false positive that cannot be designed away: gosec G101 matches the literal "GITHUB_TOKEN" against its list of known credential patterns, but this is the NAME of an environment variable, not a secret — and it is the name GitHub's own tooling uses, so it cannot be spelled differently. Renaming the constant does not help; gosec keys on the value. The sibling providers escape only because "GITEA_TOKEN" and "DIRECT_TOKEN" are not on that list.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type GitHubReleaseProvider ¶
type GitHubReleaseProvider struct {
// contains filtered or unexported fields
}
GitHubReleaseProvider implements forge.Provider.
func (*GitHubReleaseProvider) DownloadReleaseAsset ¶
func (p *GitHubReleaseProvider) DownloadReleaseAsset(ctx context.Context, owner, repo string, asset forge.ReleaseAsset) (io.ReadCloser, string, error)
func (*GitHubReleaseProvider) GetLatestRelease ¶
func (*GitHubReleaseProvider) GetReleaseByTag ¶
func (*GitHubReleaseProvider) ListReleases ¶
func (p *GitHubReleaseProvider) ListReleases(ctx context.Context, owner, repo string, limit int) ([]forge.Release, error)
ListReleases returns up to limit releases, paginating across GitHub's pages until the limit is met or history is exhausted. A limit <= 0 means "no explicit bound" — the natural first page. See forge.Provider.
func (*GitHubReleaseProvider) Login ¶ added in v0.2.0
Login implements the optional forge.Authenticator capability via GitHub's OAuth device flow (RFC 8628): it requests a device code, surfaces it through the forge.Prompter for the user to enter in a browser, then polls for the access token. Presentation — including whether to open a browser at the verification URL — belongs to the Prompter; this adapter speaks only the protocol.
It returns an error wrapping forge.ErrNotSupported when no OAuth client ID is configured (Settings.ClientID or DefaultClientIDEnv), so the caller falls back to manual token entry.
func (*GitHubReleaseProvider) UploadKey ¶ added in v0.2.0
UploadKey implements the optional forge.KeyManager capability: it registers an OpenSSH-format public key on the authenticated account via GitHub's user-keys API. The provider's resolved token (see Settings.Auth) authorises the call; name is the label shown in the account's key list.
type Settings ¶
type Settings struct {
ReleaseSource forge.ReleaseSourceConfig
// APIURL overrides the API endpoint. Empty derives it from
// ReleaseSource.Host, or uses github.com.
APIURL string `json:"api_url" yaml:"api_url"`
// UploadURL overrides the asset-upload endpoint. Empty derives it from
// APIURL.
UploadURL string `json:"upload_url" yaml:"upload_url"`
// Auth carries the credential reference resolved by [forge.ResolveToken].
Auth forge.AuthConfig
// ClientID is the OAuth app client ID used by the interactive device-flow
// login ([Authenticator]). Empty falls back to [DefaultClientIDEnv]; when
// neither is set, Login reports [forge.ErrNotSupported] and the caller
// prompts for a token manually.
ClientID string `json:"client_id" yaml:"client_id"`
// Scopes overrides the OAuth scopes requested at login. Empty uses a
// sensible default (repo, read:org, gist).
Scopes []string `json:"scopes" yaml:"scopes"`
}
Settings contains the typed configuration needed to construct a GitHub release provider, without binding it to any config container.
The shape matches every other provider: a release source, a forge.AuthConfig, and the endpoint overrides this forge needs.
func SettingsFromConfig ¶
func SettingsFromConfig(src forge.ReleaseSourceConfig, cfg forge.TokenConfig) Settings
SettingsFromConfig adapts the github config subtree into typed provider settings. It preserves the existing `url.*` and `auth.*` key layout.
Source Files