Conventions for changing and reviewing HTTP requests, host selection, authentication, and GitHub Enterprise Server (GHES) capability checks.
| Operation | Host source |
|---|---|
| Repository-scoped operation | Resolve the repository with the command's existing selection path, then use repo.RepoHost() |
| Explicit host flag or URL | Respect the command's existing validation and precedence; do not replace it with a default |
| Operation that needs a configured default | Use cfg.Authentication().DefaultHost() |
ghinstance.Default() always returns github.com; it is not user-selected
host resolution. Do not mechanically replace it with DefaultHost() either:
first determine whether the operation already has an explicit or repository
host. A default must not override a repository selected by -R or GH_REPO.
See listRun, issueList, and milestoneByNumber in
issue/list for resolved-repository host use,
and AuthConfig.DefaultHost in config.go
for configured default behavior. Preserve delayed Factory binding described in
Command development.
Obtain the command's configured HTTP client from its existing dependency.
factory.New and HttpClientFunc wire
configuration, authentication, I/O, and transport behavior. Do not substitute a
bare client, copy token lookup, or hand-build an API endpoint for a normal
GitHub API operation.
api.NewClientFromHTTP wraps that client. Reuse its
GraphQL/Query/Mutate and REST methods, or the existing request surface
appropriate to the response. Pass the chosen host and a relative API path.
Preserve endpoint-specific headers, scopes, redirect policy, error handling,
and pagination through the shared abstractions. Avoid extra round trips and
request only fields the command needs, including requested JSON export fields.
When changing API routing or constructing a client/request, also read
api_host; consult its
test harness when exercising routing changes.
The logical GitHub host still owns authentication, Git remotes, and web URLs;
an API gateway is not a replacement repository host. Do not assume every
command or service is already migrated or should use the gateway.
Reuse featuredetection.Detector
and existing capability definitions instead of scattered version tests.
Construct the detector for the target host using the existing client/cache
pattern. Propagate detection errors rather than treating them as unsupported.
Use temporary feature detection when an API is not yet generally available on all supported GitHub API servers, including GHES. Skip new gates for long-established APIs already available everywhere supported. Check current capability documentation and support requirements; do not infer readiness from GitHub.com behavior alone.
For a temporary gate that will eventually disappear, put
// TODO <cleanupIdentifier> directly above the if statement. Use the same
identifier across related call sites and capability definitions so the fallback
can be removed consistently. IssueFeatures.ApiActorsSupported in the detector
is an example of a capability with a documented cleanup condition. This is a
repository convention, not a claim about a particular linter.
Permanent gates for features that will not be supported on GHES do not need a cleanup comment. Do not remove a gate just because one host supports it; verify its cleanup condition across the current supported server range.
Before changing tests, read Testing. Cover the relevant selected
and default-host paths (including a non-github.com host), and supported versus
unsupported capability behavior. Assert the actual destination, not merely that
a mocked response was consumed.