ref(api): resolve UNKNOWN publish_status for release and deprecated endpoints by gricha · Pull Request #116650 · getsentry/sentry

gricha · 2026-06-01T22:51:59Z

Resolves the ApiPublishStatus.UNKNOWN placeholder on 10 endpoints and removes their entries from the publish-status allowlist. First batch of an effort to drain api_publish_status_allowlist_dont_modify.py and eventually delete the UNKNOWN status. publish_status is docs-only, so there is no runtime, routing, or auth change here.

All touched endpoints → PRIVATE

For now these are marked PRIVATE (not published as public API), clearing them out of UNKNOWN: the release CRUD endpoints (OrganizationReleases, OrganizationReleasesStats, OrganizationReleaseCommits, ProjectReleases POST, ProjectReleaseDetails, ProjectReleaseCommits), the @deprecated group stats/tags/integration-details endpoints, and the project releases deploy-token endpoint.

ProjectReleases GET stays PUBLIC — it was already public before this branch; only the POST we touched flips.

OpenAPI documentation is kept (intentionally)

Even though these are PRIVATE, they keep full @extend_schema documentation (params, responses, descriptions, examples). We want this documentation in place and intend to start requiring it on private endpoints, since internal changes will be driven off the generated schema/types. The docs are dormant in the public schema today but ready.

Shared schema/type fixes

Annotated UserField with @extend_schema_field(OpenApiTypes.STR) (matches api/fields/actor.py / sentry_slug.py).
Added help_text to ReleaseSerializer's status/version/owner fields.
Added COMMIT and release-timeseries example fixtures to release_examples.py.

Design note

Reviewed against the API design guidelines. One pre-existing deviation documented inline on ReleaseSerializerResponse.id: the release id is an integer rather than a string. Long-standing, codebase-wide; not introduced here.

Verified: make build-api-docs (--validate --fail-on-warn) clean, and mypy clean on all touched files.

@deprecated

These endpoints were ApiPublishStatus.UNKNOWN. They are not public API surface, so mark them PRIVATE to record intent (docs-only change, no runtime effect): - group stats/tags/integration-details: already @deprecated (cell-silo retirement) - project releases token: provisions/rotates a deploy-token credential

Promote release CRUD endpoints from ApiPublishStatus.UNKNOWN to PUBLIC with full OpenAPI documentation (extend_schema params/responses/descriptions), and remove their entries from the publish-status allowlist: - OrganizationReleases (GET+POST), OrganizationReleasesStats (GET), OrganizationReleaseCommits (GET) - ProjectReleases (POST), ProjectReleaseDetails (GET/PUT/DELETE), ProjectReleaseCommits (GET) Supporting schema fixes: - annotate UserField with extend_schema_field(STR) so serializers using it resolve cleanly (matches actor.py / sentry_slug.py) - add help_text to ReleaseSerializer status/version/owner fields

cvxluo

lgtm, though i'm not familiar enough with the releases API to feel confident approving. one thing that might be helpful is to add api doc examples. i've also generally found that there's a decent bit of type drift between the actual response schemas for endpoints vs their serializers, so it may be worth verifying that the schemas line up (e.g. i spot checked ProjectReleaseDetailsEndpoint and it seems like the HealthData schema returns floats instead of ints)

cvxluo · 2026-06-01T22:55:16Z

fyi i'm looking to publish this one

yup sg as well!

cvxluo · 2026-06-01T22:58:01Z

 class GroupStatsEndpoint(GroupEndpoint, StatsMixin):
    publish_status = {
-        "GET": ApiPublishStatus.UNKNOWN,
+        "GET": ApiPublishStatus.PRIVATE,


i think it's fine to mark these are private, but for i believe these are getting deprecated as part of the cell project, so it shouldn't matter in the long run

yeah, they can remove them then, im fine with that, i just want to kill the unknown allowlist

gricha · 2026-06-02T00:58:49Z

yeah @azulus is helping with making sure drift isn't present via linters, i'll check the Health ones you mention!

Match the established public-endpoint style (examples= alongside responses=, as the sibling ProjectReleases GET already does). Reuse the existing RELEASE fixture for release-shaped responses and add COMMIT + release-timeseries example fixtures.

…lizerResponse

azulus · 2026-06-02T16:18:53Z

    publish_status = {
-        "GET": ApiPublishStatus.UNKNOWN,
-        "POST": ApiPublishStatus.UNKNOWN,
+        "GET": ApiPublishStatus.PUBLIC,


should these be public now?

azulus · 2026-06-02T16:19:50Z

+    owner = ApiOwner.TELEMETRY_EXPERIENCE
    publish_status = {
-        "GET": ApiPublishStatus.UNKNOWN,
+        "GET": ApiPublishStatus.PUBLIC,


should we consider going unknown -> private instead of straight to public? what are the implications here?

azulus · 2026-06-02T16:20:54Z

+    owner = ApiOwner.TELEMETRY_EXPERIENCE
    publish_status = {
-        "GET": ApiPublishStatus.UNKNOWN,
+        "GET": ApiPublishStatus.PUBLIC,


similar question about unknown -> public. Remember that anything going to public likely needs to be supported forever. I don't think we want this?

azulus · 2026-06-02T16:21:07Z


    @extend_schema(
        operation_id="List an Organization Release's Commits",
-        parameters=[CursorQueryParam],


similar question about schema shape changes

azulus · 2026-06-02T16:21:21Z

+    owner = ApiOwner.TELEMETRY_EXPERIENCE
    publish_status = {
-        "GET": ApiPublishStatus.UNKNOWN,
+        "GET": ApiPublishStatus.PUBLIC,


also unknown -> public

azulus · 2026-06-02T16:21:36Z


    @extend_schema(
        operation_id="List a Project Release's Commits",
-        parameters=[CursorQueryParam],


another shape change. fine?

azulus · 2026-06-02T16:21:59Z

-        "DELETE": ApiPublishStatus.UNKNOWN,
-        "GET": ApiPublishStatus.UNKNOWN,
-        "PUT": ApiPublishStatus.UNKNOWN,
+        "DELETE": ApiPublishStatus.PUBLIC,


also unknown -> public

azulus · 2026-06-02T16:22:30Z

            )
        )

+    @extend_schema(


I'm guessing default w/ no visibility is public? should probably be private annotated?

azulus · 2026-06-02T16:22:39Z

            ),
        )

+    @extend_schema(


same comment re: visibility

Keep the @extend_schema documentation (params/responses/examples) but set publish_status to PRIVATE rather than PUBLIC. We want this documentation present -- and intend to start requiring it on private endpoints to drive internal changes off the schema -- without yet committing these as public API. project_releases GET stays PUBLIC (pre-existing); only the POST we touched flips.

gricha added 2 commits June 1, 2026 15:51

github-actions Bot added the Scope: Backend Automatically applied to PRs that change backend components label Jun 1, 2026

gricha marked this pull request as ready for review June 1, 2026 22:52

gricha requested review from a team as code owners June 1, 2026 22:52

cvxluo reviewed Jun 1, 2026

View reviewed changes

gricha requested a review from azulus June 2, 2026 00:58

gricha added 2 commits June 1, 2026 18:04

ref(releases): document pre-existing int id deviation on ReleaseSeria…

fe605ea

…lizerResponse

azulus reviewed Jun 2, 2026

View reviewed changes

gricha changed the title ~~ref(api): resolve UNKNOWN publish_status for releases and deprecated endpoints~~ ref(api): resolve UNKNOWN publish_status for release and deprecated endpoints Jun 2, 2026

azulus approved these changes Jun 2, 2026

View reviewed changes

Uh oh!

Conversation

gricha commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cvxluo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gricha commented Jun 2, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gricha commented Jun 1, 2026 •

edited

Loading