fix!: Correct HostedRunner image struct fields and JSON tags to match API

[austenstone]

Summary

Fix incorrect JSON field names on HostedRunner and HostedRunnerImageDetail structs that don't match the GitHub API response, and rename the Go struct fields to align with the API spec.

Supersedes #4102 — recreated as a single commit under my identity to resolve a CLA issue caused by a Copilot-authored gofmt commit in the original PR.

Problem

The HostedRunner struct uses json:"image_details" but the GitHub API returns the field as "image". Similarly, HostedRunnerImageDetail.SizeGB uses json:"size_gb" but the API returns "size".

This means API responses were not being deserialized correctly into these structs.

Changes

Struct	Field	Before (Go / JSON)	After (Go / JSON)
HostedRunner	Image	ImageDetails / json:"image_details"	Image / json:"image"
HostedRunnerImageDetail	Size	SizeGB / json:"size_gb"	Size / json:"size"

Both Go field names and JSON tags are updated to match the API spec. Accessors regenerated via go generate.

Breaking Change

This is a breaking change for anyone referencing the old Go field names (ImageDetails, SizeGB) or constructing JSON with the old field names. However, actual API responses were never being parsed correctly with the old tags, so this is effectively a bugfix.

Testing

• All existing hosted runner tests pass
• Marshal/unmarshal tests updated for both org and enterprise endpoints
• Generated accessor tests pass

[alexandear]

According to https://docs.github.com/en/rest/actions/hosted-runners?apiVersion=2022-11-28#list-github-hosted-runners-for-an-organization, HostedRunner contains the image_details field and not image.

Currently, the library uses 2022-11-28 API version:

go-github/github/github.go

Line 41 in 247ddc3

defaultAPIVersion = "2022-11-28"

This PR should be done as part of #4077

[Not-Dhananjay-Mishra]

Even on 2026-03-10 API Version it mentioned image_details and size_gb in response schema.
or I am missing something?

https://docs.github.com/en/rest/actions/hosted-runners?apiVersion=2026-03-10#list-github-hosted-runners-for-an-organization

[austenstone]

I dug into this and found the root cause. The internal OpenAPI schema in github/github at app/api/description/components/schemas/actions-hosted-runner.yaml does define the field as image_details, not image:

properties:
  image_details:
    $ref: './actions-hosted-runner-pool-image.yaml'
    x-nullable-ref: true

And the referenced actions-hosted-runner-pool-image.yaml uses size_gb:

properties:
  id:
    type: string
    example: ubuntu-20.04
  size_gb:
    description: Image size in GB.
    type: integer
    example: 86

So the original PR #3487 by @atilsensalduz was based on the OpenAPI schema definition, which is the source of truth.

The issue is that the rendered API docs examples show "image" and "size" in the JSON response samples, which contradicts the schema. This appears to be a documentation bug on GitHub's side — the example responses don't match the schema definition.

To know for sure which is correct, someone would need to make a live API call to GET /orgs/{org}/actions/hosted-runners and inspect the raw JSON response to see whether the field is actually image_details or image.

[austenstone]

Confirmed via a live API call. The actual API response uses image_details and size_gb, not image/size:

{
  "id": 24,
  "name": "windows-2022-16core",
  "image_details": {
    "id": "2298",
    "size_gb": 256,
    "display_name": "Windows Server 2022",
    "source": "github",
    "version": "latest"
  },
  ...
}

So the current code in master is correct. The rendered API docs examples are wrong — they show "image" and "size" but the actual API returns "image_details" and "size_gb". This PR should be closed.

[austenstone]

Traced the root cause. This is a docs bug in github/github — the OpenAPI schema and the example responses have been inconsistent since the hosted runners API was first added.

The bug: In commit cfefa504 (May 2024, by @gdryke — "reviving the hosted runner API"), the schema was correctly defined with image_details and size_gb:

# actions-hosted-runner.yaml (schema) ✅
properties:
  image_details:
    $ref: './actions-hosted-runner-image.yaml'

# actions-hosted-runner-image.yaml (schema) ✅  
properties:
  size_gb:
    type: integer

But the example files created in the same commit used the wrong field names:

# actions-hosted-runner.yaml (example) ❌
value:
  image:          # should be image_details
    id: "ubuntu-20.04"
    size: 86      # should be size_gb

Two subsequent commits (400f3d0c by @pjquirk, 1ca63a0e by @AzureRaj) modified the examples but never fixed this mismatch.

The flow: github/github examples → published to github/rest-api-description → rendered by github/docs-internal → displayed on docs.github.com.

The schema is correct (image_details/size_gb), the live API returns image_details/size_gb, but the hand-written example responses in github/github at app/api/description/components/examples/ use the wrong names image/size, and those examples are what gets displayed in the docs.

Files that need to be fixed in github/github:

• app/api/description/components/examples/actions-hosted-runner.yaml — change image: → image_details: and size: → size_gb:
• app/api/description/components/examples/actions-hosted-runner-paginated.yaml — same changes

cc @github/hosted-runners