Add the missing keys to the submodule update example response

José M. Requena Plensrequested to merge
gitlab-community/gitlab-org/gitlab:jmrp-submodule-update-example-keys into master

What does this MR do?

@PatrickRice asked on gitlab-org/api/client-go!3085 (merged) for a merge request here that brings the API documentation in line with the fields that MR adds to client-go. For the submodule update endpoint those fields are five response keys, and the page's example response shows none of them. This MR adds them to that example and changes nothing else on the page.

PUT /projects/:id/repository/submodules/:submodule presents the new commit with API::Entities::CommitDetail (submodules.rb, line 31 and line 64). That entity sends these keys with no condition:

The example showed status and none of the other five. I added them in the order the entity exposes them, after authored_date and around status, without moving the keys already there:

  • trailers and extended_trailers are {}, because the example's commit message has no trailers.
  • web_url is the example URL the Commit entity documents, which already ends in the commit SHA this example uses.
  • project_id is 5, the project in the curl example.
  • last_pipeline is null for the same reason status is already null: the example commit has no pipeline.

stats stays out. CommitDetail sends it only with include_stats, and this route does not pass it.

The generated OpenAPI document already lists all five keys for this route, under APIEntitiesCommitDetail (openapi_v3.yaml, lines 94361 to 94384), so nothing changes there. I know the API documentation is moving to the generated spec, and that on !259766 a technical writer asked to hold off on expanding the Markdown pages. This adds no table rows and no sections: it only makes the keys of the existing example match the keys the route returns, while the OpenAPI tag for this route still links to this page as its documentation (submodules.md, line 3).

How I checked what the route returns

  • Code, at master 60d9f74b: the route, the two entities and the presenter they go through (CommitPresenter#status_for). last_pipeline represents commit.lazy_latest_pipeline, which is nil for a commit without a pipeline, and Grape renders it as null. A commit read back from Gitaly with no trailers has {} for both trailers and extended_trailers (Gitlab::Git::Commit#init_from_gitaly).

  • A request spec I ran locally on this branch, not part of this MR: it calls the endpoint for a test project and compares the keys of the response with the keys of this page's example. It passes on this branch. Pointed at the page as master has it, it fails, and the keys it reports missing from the example are exactly extended_trailers, last_pipeline, project_id, trailers and web_url. The test environment runs no Git hooks, so no pipeline could exist there, and the null values it saw for status and last_pipeline say nothing about pipeline timing on a real instance. The response it recorded:

    {
  "id": "8a65d487741c5fd714e592ec83c634db79d8f752",
  "short_id": "8a65d487",
  "created_at": "2026-10-09T20:32:27.000+00:00",
  "parent_ids": [
    "b83d6e391c22777fca1ed3012fce84f633d7fed0"
  ],
  "title": "Update submodule reference",
  "message": "Update submodule reference",
  "author_name": "Sidney Jones1",
  "author_email": "user1@example.org",
  "authored_date": "2026-10-09T20:32:27.000+00:00",
  "committer_name": "Sidney Jones1",
  "committer_email": "user1@example.org",
  "committed_date": "2026-10-09T20:32:27.000+00:00",
  "trailers": {},
  "extended_trailers": {},
  "web_url": "http://localhost/user1/project-1/-/commit/8a65d487741c5fd714e592ec83c634db79d8f752",
  "status": null,
  "project_id": 4,
  "last_pipeline": null
}

  • Response schema: the new example validates against spec/fixtures/api/schemas/public_api/v4/commit/detail.json, the schema spec/requests/api/commits_spec.rb holds CommitDetail responses to. The example on master fails it, for missing web_url, project_id and last_pipeline.

  • OpenAPI document, same commit: the route's 200 response refers to APIEntitiesCommitDetail, whose properties are the 18 keys of the new example plus stats.

Lint
  • markdownlint-cli2 0.23.2 and Vale 3.21.0, in the image the docs-lint markdown job uses: no markdownlint issues and no Vale errors. Vale at warning level reports nothing on the page, before or after.
  • lychee --offline --no-progress --include-fragments on the page, as the docs-lint links job runs it: 0 errors.
  • The edited JSON block parses with jq.
Where this comes from

I maintain gitlab-mcp-server, an MCP server that exposes the GitLab API to AI assistants and is built on client-go. It reads these five keys from the raw response because client-go's SubmoduleCommit struct did not model them, and gitlab-org/api/client-go!3085 (merged) adds them. The client-go reviewers match the library's structs against the API documentation, which is why they asked for the page to show the same keys.

Related issues

Related to gitlab-org/api/client-go!3085 (merged)

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

Merge request reports