Move compatibility for non github.com targets to `github.With<THING>` options

[stevehipwell]

I propose that all compatibility functionality not required for the github.com target be removed from the default client setup and only be included via a github.With<THING> option. This (hopefully) would make the default client surface area simpler to understand. The justification for this is that you already need to use github.WithEnterpriseURLs to target non github.com. I propose the following changes to adopt this pattern, with the potential for other capabilities (such as enabling/disabling preview endpoints) to be added later.

• Default to the latest API version (2026-03-10)
  • Functions that require a specific version now check against the client version and error if not valid
• Add github.WithAPIVersion to explicitly set a version
  • Set at the client/service level
• Add github.WithAdvancedServer to enable GHAS support
  • Better validation of inputs
  • Support setting version
  • Add compatibility accordingly
• Add github.WithEnterpriseCloud to enable GHEC support
  • Better validation of inputs
• Deprecate github.WithEnterpriseURLs

I'd appreciate any feedback on this proposal.

cc: @gmlewis - @alexandear - @zyfy29 - @Not-Dhananjay-Mishra - @munlicode

[gmlewis]

That sounds like a good plan to me.
The only thing that I'm a bit confused about is this:

Functions that require a specific version now check against the client version and error if not valid

It was my understanding that endpoints that need a specific version can state that version explicitly so that the end user doesn't even need to worry about API versioning, and so we would handle all this for them in this client library.

[alexandear]

The idea in general is great, and I fully support it.

Default to the latest API version
Add github.WithAPIVersion to explicitly set a version

My only concern is migrating to the latest API version. This will be done in #4077. It requires a LOT of work.

[stevehipwell]

@gmlewis at the moment we set the version explicitly, which works fine for github.com where all of the version are currently present. But this doesn't provide an explicit error if the API version is unavailable and doesn't quite fit with an explicit version pattern. I was thinking that endpoints requiring a version check would do something like below:

minVersion := api20260310
if s.version < api20260310 {
	return VersionNotSupportedErr
}

@alexandear using the latest version could be separated from the other changes. We could still manage the client version in cases where it makes sense (such as GHAS), but leave the current defaults (effectively unset) until we were in a position to make the latest version default.

[danyalahmed1995]

I think it may be safer to split the API version work from the enterprise / compatibility option cleanup.

One possible path:

1. Add a client-level API version setting, for example WithAPIVersion, while keeping the current default behaviour unchanged.
2. Keep the existing per-request WithVersion override for cases where callers need to test or migrate individual calls.
3. Add a small internal min-version helper/error path, then migrate only the endpoints that actually need explicit version checks.
4. Once that shape is settled, layer the enterprise-specific options on top and deprecate WithEnterpriseURLs separately.

That would avoid coupling the 2026-03-10 migration from #4077 with the broader enterprise option redesign, and should make the work easier to review in smaller PRs.

Maybe just the client-level API version option plus tests, without changing the default version yet. What you guys think 😅 ?

[stevehipwell]

@danyalahmed1995 I'm not talking about changing the per-request WithVersion as that's what the service methods use if they need a specific version. I'm specifically talking about having a client level version set and using that to control the behaviour of the service methods, initially this could default to an unset version which would behave the same as it currently does.

For example this existing code:

func (s *PrivateRegistriesService) GetOrganizationPrivateRegistry(ctx context.Context, org, secretName string) (*PrivateRegistry, *Response, error) {
	u := fmt.Sprintf("orgs/%v/private-registries/%v", org, secretName)

	req, err := s.client.NewRequest(ctx, "GET", u, nil, WithVersion(api20260310))
	if err != nil {
		return nil, nil, err
	}

	var privateRegistry PrivateRegistry
	resp, err := s.client.Do(req, &privateRegistry)
	if err != nil {
		return nil, resp, err
	}

	return &privateRegistry, resp, nil
}

Becomes something like:

func (s *PrivateRegistriesService) GetOrganizationPrivateRegistry(ctx context.Context, org, secretName string) (*PrivateRegistry, *Response, error) {
	minVersion := api20260310
	u := fmt.Sprintf("orgs/%v/private-registries/%v", org, secretName)

	v := s.apiVersion
	if v == nil {
		v = api20260310
	}

	if v < minVersion {
		return nil, nil, fmt.Errorf("version %v lower than min version %v", v, minVersion)
	}

	req, err := s.client.NewRequest(ctx, "GET", u, nil, WithVersion(v))
	if err != nil {
		return nil, nil, err
	}

	var privateRegistry PrivateRegistry
	resp, err := s.client.Do(req, &privateRegistry)
	if err != nil {
		return nil, resp, err
	}

	return &privateRegistry, resp, nil
}

Although the version check would be a reusable so this is what we'd see:

func (s *PrivateRegistriesService) GetOrganizationPrivateRegistry(ctx context.Context, org, secretName string) (*PrivateRegistry, *Response, error) {
	u := fmt.Sprintf("orgs/%v/private-registries/%v", org, secretName)

	v, err := s.checkVersion(api20260310)
	if err != nil {
		return nil, nil, err
	}

	req, err := s.client.NewRequest(ctx, "GET", u, nil, WithVersion(v))
	if err != nil {
		return nil, nil, err
	}

	var privateRegistry PrivateRegistry
	resp, err := s.client.Do(req, &privateRegistry)
	if err != nil {
		return nil, resp, err
	}

	return &privateRegistry, resp, nil
}

[danyalahmed1995]

Oh yes right
I mixed up the request-level mechanism with the client-level state a bit 😅. Keeping WithVersion as the request option, but adding client-level version state for service methods to check, seems cleaner 🤔.

A small first PR for the client-level option + reusable checkVersion helper, without changing the default behavior yet, sounds like a good starting slice to me. What you think?