[Feature Proposal] - Publish and version Agones gRPC protobuf definitions

[lusu007]

Is your feature request related to a problem? Please describe.
Currently, Agones does not publish its gRPC protobuf definitions as a versioned, consumable artifact. This makes it difficult for external services and tooling to reliably integrate with Agones using gRPC without manually copying proto files or vendoring the Agones repository. As a result, keeping gRPC clients in sync with Agones API changes is error-prone and increases maintenance overhead.

Describe the solution you'd like
Agones should officially publish its gRPC protobuf definitions in a reusable and versioned form. This could be achieved by:

• Publishing the .proto files as part of the Agones release process
• Making them available via a well-known location (e.g. a dedicated GitHub repository, release assets, or a package registry)
• Ensuring the published protos are versioned consistently with Agones releases

This would allow downstream consumers to depend on Agones gRPC APIs in a clean, automated, and reproducible way.

Describe alternatives you've considered

• Manually copying proto files from the Agones repository into downstream projects
• Vendoring the full Agones repository to access the protos
• Maintaining a community-driven fork that publishes the protos independently

All of these approaches add friction, increase the risk of version drift, and place unnecessary burden on integrators.

Additional context
Publishing the gRPC protos would significantly improve the developer experience for anyone building external controllers, services, or tooling around Agones. It would also align with common practices in other CNCF projects that expose gRPC APIs.

Link to the Agones Feature Proposal (if any)
N/A

Discussion Link (if any)

N/A

[markmandel]

Thanks for the issue - a few questions:

Do you have specific gRPC files in mind? We have some for the allocation endpoints, and some for the SDK as well. Or is it both?

Many of our Protos only change occasionally, and are backward compatible -- I'm curious what exact issues you're running into with moving between Agones versions?

It seems like doing a manual copy over when you upgrade Agones would be not be that onerous a process (could write a script for it to temporarily close the repo, or even do a git sparse-checkout?. You honestly could do a manual copy paste over when you need a feature that's in a specific proto version. Otherwise you could probably just leave it alone -- that being said, that's why I'm asking about what specific issues you are running into / integration patterns you are running, because it's likely I'm missing something here, and want to make sure all bases are covered.

That all being said, zipping up the proto (and likely openapi/swagger files) and including them as a release artifact seems like a reasonable thing to do, and a pretty low lift operation.

[lusu007]

Thanks for the issue - a few questions:

Do you have specific gRPC files in mind? We have some for the allocation endpoints, and some for the SDK as well. Or is it both?

Many of our Protos only change occasionally, and are backward compatible -- I'm curious what exact issues you're running into with moving between Agones versions?

It seems like doing a manual copy over when you upgrade Agones would be not be that onerous a process (could write a script for it to temporarily close the repo, or even do a git sparse-checkout?. You honestly could do a manual copy paste over when you need a feature that's in a specific proto version. Otherwise you could probably just leave it alone -- that being said, that's why I'm asking about what specific issues you are running into / integration patterns you are running, because it's likely I'm missing something here, and want to make sure all bases are covered.

That all being said, zipping up the proto (and likely openapi/swagger files) and including them as a release artifact seems like a reasonable thing to do, and a pretty low lift operation.

Thanks for the questions, happy to clarify.
Ideally this would include both the allocation protos and the SDK protos, since external services often depend on one or the other (and sometimes both).

We’re not running into frequent breaking changes — the main challenge is less about compatibility and more about distribution and versioning. There’s currently no canonical, versioned artifact that clearly represents “the gRPC APIs for Agones version X.Y.Z”. As a result, consumers need to vendor the repo or manually copy files, which adds friction and makes automation, reproducible builds, and multi-language usage harder.

Manual copying works in simple cases, but it doesn’t scale well once multiple services, CI pipelines, or non-Go ecosystems are involved.

That’s why attaching the gRPC protos as release artifacts would already be a big improvement and a very reasonable, low-effort first step.

[markmandel]

As a result, consumers need to vendor the repo or manually copy files, which adds friction and makes automation, reproducible builds, and multi-language usage harder.

Just because curious - are you able to share the specifics of what your build pipelines look like, and what specific challenges you ran into, and how you worked around them?

That’s why attaching the gRPC protos as release artifacts would already be a big improvement and a very reasonable, low-effort first step.

Sounds like an excellent idea to me. @Sivasankaran25 something you could incorporate into the release process / tooling?

[lusu007]

Just because curious - are you able to share the specifics of what your build pipelines look like, and what specific challenges you ran into, and how you worked around them?

Sure, happy to share.

We have a Java-based project with a fairly standard Gradle setup. Ideally, we’d like to consume the Agones APIs directly via gRPC. For that, we need the proto definitions available at build time so we can generate the gRPC stubs and get proper compilation and IDE auto-completion.

At the moment, since the protos aren’t easily consumable as a versioned artifact, we don’t have a clean way to integrate them into our Gradle build. As a workaround, we’re currently using the HTTP API instead.

Having the gRPC protos published (for example as release artifacts) would allow us to integrate them cleanly into the build and switch to gRPC without extra manual steps.

[markmandel]

At the moment, since the protos aren’t easily consumable as a versioned artifact, we don’t have a clean way to integrate them into our Gradle build. As a workaround, we’re currently using the HTTP API instead.

I ended up down a rabbit hole just because it's interesting -- is this a solution, or has this got problems if you go down this path in the Gradle/JVM ecosystem?

https://blog.gradle.org/introducing-source-dependencies

[lusu007]

I ended up down a rabbit hole just because it's interesting -- is this a solution, or has this got problems if you go down this path in the Gradle/JVM ecosystem?

Haha 😆

At the moment, we treat protos as regular dependencies using the implementation keyword in Gradle, not as source dependencies.

In our Gradle setup, our gRPC contracts are published and consumed as artifacts. For example:

• https://github.com/groundsgg/library-grpc-contracts
  Contains our shared gRPC proto definitions.
• https://github.com/groundsgg/service-player
  Consumes those contracts as a Gradle dependency and generates the gRPC stubs for compilation and IDE auto-completion.

We would integrate the Agones protos in the same way. Source dependencies could work as a workaround, but for protos, they introduce unnecessary coupling compared to consuming a simple, versioned artifact published with each Agones release.

[markmandel]

Iiiinteresting! Learning interesting things.

I also forgot to ask - I assume a zip of the grpc protos and swagger definition is good? (probably one for the SDK and one for allocations)?

[lusu007]

Iiiinteresting! Learning interesting things.

I also forgot to ask - I assume a zip of the grpc protos and swagger definition is good? (probably one for the SDK and one for allocations)?

A zip of the gRPC protos is fine. Having them grouped logically (e.g. one for the SDK and one for allocations) makes total sense. Including the Swagger/OpenAPI definitions alongside them would be a nice bonus, but the gRPC protos alone would already enable clean Gradle integration, code generation, and IDE support.

If you want to, you can have a look at our published packages here: https://github.com/orgs/groundsgg/packages?repo_name=library-grpc-contracts

[lacroixthomas]

Seems that we missed it for the last release, sorry about that, gonna check if we can set it on the release process to ensure it's part of the next release

[lacroixthomas]

Maybe we could add the steps on the release_issue and patch_release_issue and probably a make target to push them to the registry ? WDYT ?