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.

Discovery capabilities¶

Shipped in forge-github, forge-gitlab and forge-gitea v0.5.1, and forge-bitbucket v0.4.1.

"Never" is not a gap. Bitbucket Cloud has no static hosting, so Sites is unimplementable there rather than merely unimplemented. That is the optional-capability pattern doing its job.

forge-gitea is the row worth a second look. It registers two source types from one implementation, and only Codeberg has sites, so the same Go type implements Sites and returns ErrNotSupported when constructed for plain gitea.

Callers treat both refusals identically. See discover repositories.

Issue capabilities¶

Shipped in forge-github, forge-gitlab and forge-gitea v0.5.1.

They are split because the credential requirement differs, not for tidiness:

A read-only token satisfies Issues entirely and fails IssueFiler at the point of creation. A deployment that is not trusted to write should therefore decline the capability rather than discover the limit on its first escalation.

IssueFiler is the only capability that writes to a project. See file and watch issues, and note that KeyManager below writes to the authenticated account.

Labels on an issue¶

IssueDraft.Labels follows the same rule as PullRequestDraft.Labels, and that is deliberate: a caller learning it once should not find it means something else on the neighbouring type. Specified by spec 0017.

CreateIssue can return an issue and an error. When a label could not be applied it returns the filed issue together with an error wrapping ErrNotHonoured, so the reflexive if err != nil { return err } treats a filed report as a failure. A caller that sets no labels can never see this.

An unresolvable name is reported, not refused. A report exists to be filed; losing it over a marker is the worse outcome, and the marker is the decoration.

Getting the check wrong costs less here than elsewhere, and only because of the at-most-once guarantee: a caller that retries finds the existing issue rather than filing a duplicate — provided it set an IdempotencyKey. Without one, the retry files a second report.

Pull-request capabilities¶

The contract landed in forge v0.16.0 and every forge adapter implements it: forge-gitlab v0.13.0, forge-github v0.14.0, forge-gitea v0.15.0 and forge-bitbucket v0.10.0.

Direct is a genuine never rather than a gap. It fetches from URL templates and has no repository to propose a change against, so no implementation would make it able to; that is what separates a never from work still outstanding.

MergeRequests is a Go type alias for PullRequests, so forge-gitlab declares itself in GitLab's vocabulary and it is the same assertion:

var _ forge.MergeRequests = (*GitLabReleaseProvider)(nil)

Why the method names carry no noun, and why that is what makes the alias work, is in optional capabilities.

The credential each operation needs, in GitLab's vocabulary:

The other forges split the same way — the three reads need a token that can read the repository, and the three writes need one that can write to it.

ResolveMergedCommit is a read, but it is the one worth understanding before using this capability. It never returns the pull request's recorded head without first confirming that commit is on the target branch. GitLab is where this bites hardest, because it rebases before a fast-forward merge without writing the result back, but the guarantee is the contract's rather than any one forge's and each adapter asks its own platform the same question a different way. See optional capabilities for the whole story, and note the practical consequence: on a rebased merge request it costs a bounded walk of the target branch (at most 100 commits) rather than a single field read.

There is no Merge. Merging a release pull request is a maintainer action.

Labels¶

PullRequestDraft.Labels attaches labels when opening a pull request, and PullRequest.Labels reports the ones it carries. Specified by spec 0014.

Bitbucket's never is the platform. It has no labels anywhere — not on pull requests and not on issues, which is why it implements neither Issues nor IssueFiler. A draft carrying labels still creates the pull request there, and reports every requested label as not honoured.

Create can now return a pull request and an error. When a label could not be applied it returns the created pull request together with an error wrapping ErrNotHonoured, so the reflexive if err != nil { return err } treats a success as a failure — and because Create makes no at-most-once claim, the retry opens a second pull request. See migrating to labelled pull requests. A caller that sets no labels can never see this.

There is no way to change a pull request's labels afterwards. Mutating a label is how tools encode state on a pull request, and reading a forge record as evidence of what landed is the failure ResolveMergedCommit exists to prevent.

Release-publishing capabilities¶

ReleasePublisher creates a release against a tag, amends its notes and attaches files. The contract landed in forge v0.20.0 — v0.19.0 shipped it unimplementable, see the method migration — and every forge that has releases implements it. See each adapter's CHANGELOG for the release that carries it.

Bitbucket's never is the platform, not the effort. It has no release resource at all — this module already synthesises one from Downloads filenames on the read side, and GetReleaseByTag and ListReleases return ErrNotSupported. Writing would mean accepting a tag, a name and a body, storing none of them, and returning a release the caller could never find again.

It does not create the tag. A tag is a git object and needs no forge API, so that lives in go/repo. CreateRelease requires the tag to exist and returns ErrNotFound when it does not — see optional capabilities for why refusing matters more than it sounds.

The commit is checked, not sent, and each adapter asks its own forge a different way. GitLab's tag endpoint reports the commit directly. Gitea's does too, annotated or not. GitHub's ref reports a tag object for an annotated tag, so it needs a second dereference — miss it and every annotated tag is refused, which is what release tooling produces.

There is no DeleteRelease. Unpublishing a release is a maintainer action, the same line PullRequests draws at Merge.

Publishing a release complete, and hosted assets¶

ReleaseAssetPublisher publishes a release that already carries its assets, and attaches an asset the caller has already hosted somewhere rather than holds the bytes of. Specified by spec 0015.

It exists because CreateRelease followed by AddReleaseAsset necessarily passes through a state where the release is visible and empty, and that window fails badly rather than untidily: the release exists, so a consumer fetching an asset gets a 404 that looks like a missing file rather than a race.

The support for the two asset shapes is inverted across the family. This is the fact to read before designing against it.

Neither shape is universally supported, and the platform weakest on one is strongest on the other. GitLab's release assets are links, so its byte upload is a wrapper that publishes to the project's generic package registry and links the result. GitHub and Gitea take only bytes.

The footer is written once, at create. UpdateRelease replaces the body wholesale, so an update that does not carry the footer forward removes it. Which regions of a body are machine-owned is the caller's policy, as it is everywhere else in this contract. AddReleaseAssetLocation therefore has no footer fallback — appending to an existing body would mean a read-modify-write on every call, and that carries the lost-update race UpdateRelease already documents as unsolved.

A source carrying Content is a caller error on AddReleaseAssetLocation. That method attaches a location; handed bytes it refuses before any request, rather than quietly becoming AddReleaseAsset and hiding which path ran. The refusal carries no sentinel, exactly as ReleaseAssetSource.Validate reports a malformed source — in particular it is not ErrNotFound, which on that method means no release exists for the tag. Specified by spec 0016.

How each forge reaches the guarantee, which is stated as an observable property rather than a request count, because only one platform can do it in a single request:

A draft the caller asked for is honoured. ReleaseDraft.Draft is intent, not merely the mechanism above: where a platform models it, the same route runs and the final publish step is not taken. GitLab models neither draft nor prerelease and continues to report ErrNotHonoured for them.

If an asset fails to attach, nothing is left behind. On the draft-route platforms the provider deletes the unpublished draft it created, so a retry behaves like a first attempt rather than hitting ErrAlreadyExists against a half-built release with no verb to finish or remove it. That is not a delete capability: nothing lets a caller ask for a deletion, and the tag is untouched.

Two errors are specific to this capability. ErrAlreadyExists says the tag already carries a release. ErrNotHonoured says the release was created and some field could not be applied — it is returned with the release, so the usual if err != nil check treats a success as a failure. Read its godoc before using this capability.

The address an attached asset is fetched from¶

An asset attached through either release-publishing capability is fetchable at the address that platform conventionally serves a release asset from, not only at the location it was hosted at. The address is derived from the asset's Name. Specified by spec 0018.

Nothing on ReleaseAssetSource switches it on. A field would make the address opt-in, and every caller who did not set it would keep the same silent failure.

Where a platform attaches an asset and cannot give it a conventional address, the provider reports that with ErrNotHonoured beside the created release, and the hint names the asset. GitLab is in that position for some names, which is narrower than it sounds and worth knowing before you name an artefact:

Measured against gitlab.com on 2026-09-01. A rejected character makes GitLab refuse the whole asset link, not just the address, so the provider omits the address rather than sending a request that fails — tool_1.2.3+build.5.tar.gz reaches this through semver build metadata alone. The asset is always attached. A name this contract accepts never costs a caller the asset over an address.

Comment capabilities¶

Two capabilities post a comment: IssueCommenter on an issue, and PullRequestCommenter on a pull or merge request. Specified by spec 0021.

Bitbucket's row is the one to check before relying on it: the code is on main and its release is proposed but not yet tagged, in forge-bitbucket !105. The other three are cut.

Every forge that can carry a comment now does. The contract shipped one release ahead of its adapters, and this table published not yet against all four during that gap, which is the direction the matrix is allowed to be wrong in.

Bitbucket's never is the platform, and it is measured rather than inferred. Atlassian withdrew Bitbucket Cloud's issue tracker along with wikis and snippets; its own published API description declares zero paths containing /issues, checked on 2026-09-07. So the adapter does not implement IssueCommenter at all rather than stubbing it — a stub would make As assert successfully and tell a caller the capability exists. Pull-request comments are unaffected.

One endpoint or two, and the caller never has to know. GitLab is the only one of the four where an issue comment and a pull-request comment are genuinely different calls. On GitHub and Gitea a pull request is an issue, sharing a number space and a comment endpoint, so both capabilities route to the same place with a different number. That is the platform's model rather than the ambiguity the two-capability split refuses: the split keeps a caller from confusing an issue number with a pull request number, and by the time an adapter runs, the caller has already said which it meant by choosing the method.

The method names differ deliberately. CreateIssueComment matches IssueFiler.CreateIssue; the pull-request side is bare Comment because MergeRequests is a type alias and an alias renames a type but never a method — CreatePullRequestComment would hand the GitLab noun back at every MergeRequestCommenter call site.

At-most-once, and what it costs. CommentDraft.IdempotencyKey makes a post at-most-once across a retry: the provider looks for a comment carrying the key and returns that one rather than posting a second. The key is written with AppendIdempotencyKey, the same visible [forge-idempotency: …] marker IssueFiler uses — an HTML comment would be hidden on three forges and render as literal text on Bitbucket.

It is not atomic, the key is published, and it costs a full listing of the target's comments rather than one filtered request: no forge offers a server-side search over comments, checked at each pinned client and, for Bitbucket, against a published API description that declares no query parameters on the listing at all. PullRequestCommenter.ListRequestComments exists so that guarantee can be checked rather than merely asserted, and it returns the complete set — a partial view read as "no duplicate" is what posts the duplicate.

Wiki capabilities¶

Wikis reads and writes a project's wiki pages. Specified by spec 0020.

Two mechanisms sit under one contract, and a caller never sees which ran:

Bitbucket's never is the platform. Atlassian sunset Bitbucket Cloud's wikis alongside its issue tracker: from April 2026 they could no longer be enabled on repositories not already using them, and existing wikis were removed in mid-August 2026, with no interaction possible through the UI or the API.

Confirmed against the live API: a repository created on 2026-09-06 carries no has_wiki field and no wiki link — the feature is gone from the data model, not merely from the interface.

links: avatar, branches, clone, commits, downloads, forks, hooks, html,
       pullrequests, self, source, tags, watchers

An adapter was written against the git route before this was known and is closed unmerged. The mistake is recorded in spec 0020: Atlassian's "Clone a wiki" support page still describes the feature, and a support document describing how to use something is not evidence it exists.

GitHub's absence of an API is the platform, not its client: the REST wiki routes 404 against a repository that has a wiki, and its GraphQL schema carries one boolean about wikis and no page type.

The page's identity is its path, specs/0079-pipeline-churn, and a path written is a path read back. Each platform stores and shows it differently, and those differences are the provider's problem:

A losing write is ErrConflict. On the git-backed forges a page update is clone, edit, push, and a second writer in that window makes the push a non-fast-forward. It surfaces rather than being retried or forced: last-write-wins on a wiki holding a project's decision records is the failure this capability exists to prevent. A provider re-reads immediately before writing to narrow the window; it cannot close it.

Publishing a stranded draft¶

DraftPublisher finishes a release left unpublished by an interrupted run. Specified by spec 0022.

The two adapters find the release through opposite endpoints, and each asserts which:

A provider reaching for the wrong one reports ErrNotFound for exactly the state it was asked to recover — and the contract warns that a caller told that goes and creates a release.

Why it exists at all. CreateReleaseWithAssets guarantees no observer without write access ever sees a release without its assets. Only GitLab manages that in one request; GitHub and Gitea reach it by creating a draft, attaching, then publishing. A process killed in that window leaves the draft, and the provider's own discard-on-failure cannot help — it runs on an in-process failure, and a killed process runs no Go code.

Finding a stranded draft needs the listing, not the tag. GetReleaseByTag returns 404 for a draft on GitHub even to a writer; Gitea returns it. On both forges the release listing shows drafts to anyone with push access, and Release.GetDraft() reports the flag — so ListReleases is how a caller detects one. That asymmetry is a documented cost rather than a defect: making GetReleaseByTag uniform would put a listing scan on every call to serve a rare recovery.

There is no discard. Destroying published things is a maintainer act in this estate rather than a library call, which is why ReleasePublisher carries no delete, PullRequests no Merge and RepositoryCreator no delete. The recovery this capability offers is finishing the release.

Repository creation¶

RepositoryCreator creates a repository. Specified by spec 0019.

Implemented everywhere, and no two adapters do it the same way. That is the case for the capability existing rather than a caller writing four code paths:

It is a capability of its own rather than a method on Repositories, which is read-only by design. A tool that enumerates a namespace has said nothing about wanting to create in one, and should not acquire a write verb by upgrading.

Name is the path segment too. GitHub, Gitea and Bitbucket have one field that is both. GitLab has two — a display name and a URL path — and derives the second by slugifying the first, so that provider sends the value as both. Otherwise "My Tool" creates a repository at my-tool and the returned Path is something the caller never wrote. The returned Repository.Path is always owner + "/" + Name.

owner is required and is a path. An empty one does not mean "my own namespace", because Bitbucket has no personal namespace for such a value to name. What each provider does with the path is its own problem: GitLab resolves it to a numeric id, GitHub and Gitea choose between a user and an organisation endpoint, and Bitbucket uses it verbatim as a workspace slug.

What the draft carries, and what only some forges honour¶

Name, Description and Visibility are accepted everywhere. The other two are not, and this table is measured rather than read off documentation:

VisibilityInternal exists on GitLab and GitHub Enterprise only. A provider that cannot honour it creates the repository private, never public, and reports it. The failure has to be safe, because there is no delete here to undo it.

One create route on two forges ignores the namespace¶

This is the sharpest thing the implementation turned up, and it is not visible from any documentation.

On Gitea and GitHub, the endpoint used for a personal namespace — POST /user/repos — takes no namespace parameter at all. It creates in the authenticated user's namespace whatever the caller asked for. Measured on Gitea 1.27.3: authenticated as spike, intending the namespace other, it answered 201 and spike/ns-probe.

So the obvious mapping of "the namespace is a user, use the user endpoint" creates the repository in the wrong place and reports success, and this contract has no delete to take it back. Neither adapter does that:

Each costs one identity request on the user path. Spec 0019 D4 rejected "who am I" as a way of deciding organisation-versus-user, and this is not that: it asks as well rather than instead, because one endpoint's answer depends on it.

A collision is four forges and three status codes¶

All four map onto ErrAlreadyExists. Only one of them is 409, and the two answering 400 share that status with every malformed request — so a provider maps on the body rather than the status. A creation path reusing an existing 409 mapper is correct on Gitea and turns "this name is taken" into ErrNotFound on two of the others.

There is no delete, archive, rename or transfer, and no post-creation configuration. See spec 0019 for where those lines sit.

Account capabilities¶

Two more optional interfaces exist for a tool's first-run setup: signing a user in, and registering their SSH key. They follow the same contract as every other capability: discover with forge.As, and treat a failed assertion and ErrNotSupported identically.

var auth forge.Authenticator
if forge.As(provider, &auth) {
    token, err := auth.Login(ctx, myPrompter) // blocks until the user finishes
}

Login needs a forge.Prompter (one method, ShowDeviceCode(ctx, DeviceCode)) which you implement. That is how forge offers a device flow without taking a terminal or TUI dependency: the provider hands you the code, the URL and its expiry, and your CLI decides how to show them. Fall back to manual token entry when the assertion fails or ErrNotSupported comes back.

The device flow needs an OAuth client ID as well as the eventual token:

KeyManager.UploadKey(ctx, name, publicKey) registers an OpenSSH-format public key under a human-readable label on the authenticated account. It is a write, and it is the one write in this module that is not to a project.

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 anyway. 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 Endpoint.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, where host, port and scheme must all match. Asset URLs come from release metadata that a release author controls, so an unpinned credential hands the token to whatever host that author names. 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 Endpoint.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, which is 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. 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¶

Endpoint.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, but a plain download source (a web server, an artefact store, a CDN) with releases and 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:

url_template is the only required one, and tool_name, pinned_version, version_url, version_format, version_key, checksum_url_template and signature_url_template are optional. The configuration reference carries the table with each key's default and behaviour, so there is one copy of it rather than two.

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.

No provider refuses to build for want of a credential¶

A provider with no resolvable token proceeds anonymously, which is correct for a public repository. Whether the repository you go on to ask about is private is not knowable at construction, because one connection serves both, so there is no construction-time check to make.

forge-bitbucket handles the private case at the operation: a refusal with no credential resolved carries guidance naming the variables to set, since that is what a private repository looks like from outside. The other providers return the refusal sentinels without that hint.

The removed ReleaseSourceConfig.Private flag used to sit here; it was read by Bitbucket alone and ignored elsewhere, and went with the rest of that type in spec 0008 (D3, D8). If you are moving off that type, Migrate from ReleaseSourceConfig is the how rather than the why.

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, which usually diagnoses 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 rather than a workaround. The registry takes any string key, and nothing needs contributing here. See author a provider.

Related¶

• Configuration: every key, param and environment variable, with defaults and failure modes
• Errors: the sentinels these providers return
• What forge does not do: the limits behind the "never" entries above