README
¶
forge-github
GitHub release provider for forge
Part of the phpboyscout Go toolkit. Full documentation lives on the core module's site: forge.go.phpboyscout.uk
Implements the forge.Provider
contract for GitHub releases, using
go-github. Works against github.com and
GitHub Enterprise.
Scope: releases only, for now
This module carries only the release contract, matching its sibling providers.
GitHub's wider API — pull requests, repository creation, SSH key upload, file contents, and the OAuth device-login flow — exists in go-tool-base and is deliberately not extracted yet. Bringing it here would give one forge capabilities the others lack, which is precisely the disparity backend agnosticism exists to prevent: code written against a GitHub-only method stops being portable, and the interface stops being a contract.
Restoring those capabilities across every provider in lockstep is specified on the forge module. Until then, parity is the point.
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.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)
- type Settings
Constants ¶
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 ¶
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
}
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