README
¶
forge-gitlab
GitLab 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 GitLab releases, using
gitlab-org/api/client-go.
It is its own module so a tool that only supports GitLab never compiles
GitHub's client, Gitea's, or Bitbucket's. A depfootprint guard asserts that.
Use it
Blank-import to register, then resolve through the registry — your code never names a GitLab type:
import (
"gitlab.com/phpboyscout/go/forge"
_ "gitlab.com/phpboyscout/go/forge-gitlab"
)
factory, err := forge.Lookup("gitlab")
provider, err := factory(source, cfg)
go get gitlab.com/phpboyscout/go/forge-gitlab
Configuration
| Key | Purpose |
|---|---|
gitlab.auth.env |
Name of an environment variable holding the token |
gitlab.auth.keychain |
OS keychain reference, service/account |
gitlab.auth.value |
Literal token (weakest — avoid in committed config) |
gitlab.url.api |
Override the API endpoint |
GITLAB_TOKEN |
Well-known fallback |
ReleaseSource.Host selects a self-hosted instance; empty means gitlab.com.
A token is optional — public projects resolve unauthenticated.
Platform differences
GitLab's release model differs from GitHub's in ways the shared contract cannot hide:
| Contract | On GitLab |
|---|---|
GetDraft() |
Always false — GitLab has no draft-release concept, so there is nothing to report. Code branching on it will treat every GitLab release as published. |
DownloadReleaseAsset redirect |
Always empty. Only GitHub redirects asset requests to a CDN. |
GetLatestRelease |
Fetches the first page of releases sorted newest-first, rather than a dedicated latest endpoint. |
Security
The PRIVATE-TOKEN credential is attached only to asset downloads on the
configured instance, via
forge.HostTrusted.
Asset URLs come from release metadata that a release author controls, so an
unpinned credential is an exfiltration primitive. Host, port and scheme must all
match, which also refuses a downgrade to plaintext HTTP.
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 gitlab implements the VCS release provider for GitLab repositories, supporting both public and token-authenticated access; the owner may be a slash-separated group path passed through to the GitLab API. Provider construction uses package-owned Settings; GTB config integration lives in SettingsFromConfig.
Index ¶
- Constants
- func NewReleaseProvider(settings Settings) (forge.Provider, error)
- type GitLabReleaseProvider
- func (p *GitLabReleaseProvider) DownloadReleaseAsset(ctx context.Context, owner, repo string, asset forge.ReleaseAsset) (io.ReadCloser, string, error)
- func (p *GitLabReleaseProvider) GetLatestRelease(ctx context.Context, owner, repo string) (forge.Release, error)
- func (p *GitLabReleaseProvider) GetReleaseByTag(ctx context.Context, owner, repo, tag string) (forge.Release, error)
- func (p *GitLabReleaseProvider) ListReleases(ctx context.Context, owner, repo string, limit int) ([]forge.Release, error)
- func (p *GitLabReleaseProvider) Login(ctx context.Context, prompter forge.Prompter) (string, error)
- func (p *GitLabReleaseProvider) UploadKey(ctx context.Context, name string, publicKey []byte) error
- type Settings
Constants ¶
const DefaultClientIDEnv = "GITLAB_CLIENT_ID"
DefaultClientIDEnv is the well-known environment variable consulted for the OAuth application client ID the interactive device-flow login ([Authenticator]) requires, when Settings.ClientID is empty.
Variables ¶
This section is empty.
Functions ¶
func NewReleaseProvider ¶
NewReleaseProvider builds a GitLab release provider from explicit typed settings. A public repository needs no auth settings; Host selects the instance, empty means gitlab.com, and APIURL can override the derived API endpoint. When auth is absent, the token falls back to GITLAB_TOKEN.
Types ¶
type GitLabReleaseProvider ¶
type GitLabReleaseProvider struct {
// contains filtered or unexported fields
}
GitLabReleaseProvider implements forge.Provider.
func (*GitLabReleaseProvider) DownloadReleaseAsset ¶
func (p *GitLabReleaseProvider) DownloadReleaseAsset(ctx context.Context, owner, repo string, asset forge.ReleaseAsset) (io.ReadCloser, string, error)
DownloadReleaseAsset is more complex for GitLab.
func (*GitLabReleaseProvider) GetLatestRelease ¶
func (*GitLabReleaseProvider) GetReleaseByTag ¶
func (*GitLabReleaseProvider) ListReleases ¶
func (p *GitLabReleaseProvider) ListReleases(ctx context.Context, owner, repo string, limit int) ([]forge.Release, error)
ListReleases returns up to limit releases, paginating across GitLab's pages (signalled by the X-Next-Page header) until the limit is met or history is exhausted. A limit <= 0 means "no explicit bound" — the natural first page. See forge.Provider.
func (*GitLabReleaseProvider) Login ¶ added in v0.2.0
Login implements the optional forge.Authenticator capability via GitLab'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 (*GitLabReleaseProvider) 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 GitLab'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.
It returns an error wrapping forge.ErrNotSupported when no token is configured, since GitLab's key API requires authentication — the caller then instructs the user to add the key manually.
type Settings ¶
type Settings struct {
ReleaseSource forge.ReleaseSourceConfig
APIURL string `json:"api_url" yaml:"api_url"`
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 the provider reports the capability as unsupported.
ClientID string `json:"client_id" yaml:"client_id"`
// Scopes overrides the OAuth scopes requested at login. Empty uses a
// sensible default (GitLab `api`).
Scopes []string `json:"scopes" yaml:"scopes"`
}
Settings contains the typed configuration needed to construct a GitLab release provider without binding the provider to GTB config.
Fields are populated by the GTB config adapter via the narrow forge.TokenConfig seam, not decoded with mapstructure. The json/yaml tags are for documentation and serialisation only.
func SettingsFromConfig ¶
func SettingsFromConfig(src forge.ReleaseSourceConfig, cfg forge.TokenConfig) Settings
SettingsFromConfig adapts the gitlab config subtree into typed provider settings. It preserves the existing `url.api` and `auth.*` key layout.
Source Files