Providers¶

A provider teaches forge to talk to one release backend. Each ships as its own module — except direct, which is not a forge — so a tool links only the clients it actually uses.

Enable one with a blank import; the registry does the rest:

import (
    "gitlab.com/phpboyscout/go/forge"

    _ "gitlab.com/phpboyscout/go/forge-gitlab"
)

factory, err := forge.Lookup("gitlab")

Your code never names a provider type. See backend agnosticism.

Capability matrix¶

The redirect column matters because callers are told to refuse a non-empty redirect from DownloadReleaseAsset rather than follow it. Only GitHub ever populates it, when its API redirects an asset request to a CDN.

What the contract flattens¶

A single interface over five platforms cannot preserve every distinction. Two worth knowing, because code branching on them misbehaves silently rather than failing:

See also the honest limits in backend agnosticism.

A dash means the provider does not implement the optional interface, so callers fall back to locating the file by name among the release assets — which is how most releases publish checksums. That fallback is the normal path, not a degraded one. See optional capabilities.

GitLab¶

import _ "gitlab.com/phpboyscout/go/forge-gitlab"

Registers the source type gitlab. Works against gitlab.com and any self-hosted instance.

Configuration¶

The endpoint is derived from ReleaseSource.Host:

gitlab.url.api overrides both. See authenticate for the resolution order.

Credentials are optional¶

A public project resolves unauthenticated. A token raises rate limits and is required for private projects.

Security¶

The token travels as a PRIVATE-TOKEN header, and is attached only to asset downloads on the configured instance — host, port and scheme must all match. Asset URLs come from release metadata that a release author controls, so an unpinned credential is an exfiltration primitive. See credential pinning.

GitHub¶

import _ "gitlab.com/phpboyscout/go/forge-github"

Registers the source type github. Works against github.com and GitHub Enterprise.

Configuration¶

For Enterprise, set ReleaseSource.Host and both 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.

Credentials are optional; public repositories resolve unauthenticated.

Bitbucket¶

import _ "gitlab.com/phpboyscout/go/forge-bitbucket"

Registers the source type bitbucket, over the Downloads API — a file bucket rather than a release system. It is a deliberately partial provider: there are no tags and no release list, so GetReleaseByTag and ListReleases return ErrNotSupported and callers fall back.

It is the only provider implementing both optional interfaces, locating checksums.txt and checksums.txt.sig by exact filename — because without a release object there is nothing else to hang a manifest on.

Configuration¶

Bitbucket needs two credentials, not a single token:

One keychain entry rather than two, because a username and app password are useless apart. Version detection reads the version from asset filenames; override with the filename_pattern param.

Credentials travel as basic auth, which makes the scheme check in credential pinning matter more here than elsewhere.

Gitea and Codeberg¶

import _ "gitlab.com/phpboyscout/go/forge-gitea"

Registers two source types from one implementation. Codeberg is a Gitea instance, so they differ only in a pre-seeded host and which variable supplies the token:

Splitting them into separate modules would mean duplicating the provider to change two constants.

Configuration¶

ReleaseSource.Host selects the instance. Credentials are optional; public repositories resolve unauthenticated.

Security¶

The token travels as an Authorization header, attached only to asset downloads on the configured instance. See credential pinning.

Direct¶

import _ "gitlab.com/phpboyscout/go/forge/direct"

Registers the source type direct. Not a forge: a plain download source — a web server, an artefact store, a CDN — with releases but no API to ask about them. It ships inside the core module because it will never need a vendor SDK, and doubles as the contract's reference implementation.

Because there is no API, the URLs are composed from templates and the latest version has to be told to it. Full setup is in use the direct provider; the keys are:

Neither pinned_version nor version_url set means a version check returns ErrVersionUnknown — assuming a version silently would be worse. The token travels as a Bearer header.

ReleaseSource.Private¶

Setting Private: true makes a missing credential a fast failure rather than an unauthenticated attempt. Leave it false and a provider with no resolvable token proceeds anonymously, which is correct for a public repository and gives a clearer error than a late 404 when the repository is private.

Registry API¶

forge.RegisteredTypes()      // sorted []string of every registered source type
forge.Registered("gitlab")   // is this type registered?
forge.Unregister("gitlab")   // deliberately replace a built-in

RegisteredTypes is what Lookup's error message lists when a type is unknown — usually diagnosing a missing blank import. Constants exist for the first-party set (forge.SourceTypeGitHub and friends), but the registry accepts any string, so they are a convenience rather than a constraint.

Adding your own¶

All first-party providers ship: GitHub, GitLab, Gitea, Codeberg, Bitbucket and plain download sources.

Your own is a first-class peer, not a workaround — the registry takes any string key, and nothing needs contributing here. See author a provider.