[REST] Document `/code-scanning/analysis`

[jsoref]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28#list-code-scanning-analyses-for-a-repository

What part(s) of the article would you like to see updated?

Add a section to document the api that's actually used by:
https://github.com/github/codeql-action/blob/5eb3ed6614230b1931d5c08df9e096e4ba524f21/lib/upload-lib.js#L238-L253

At the very least, the following fields should be documented:

{
    "commit_oid": "da0dbe0dbab41d021032734315ce98bc385f51a4",
    "ref": "refs/pull/2/merge",
    "analysis_key": ".github/workflows/zizmor.yml:zizmor",
    "analysis_name": "zizmor",
    "sarif": "H4sIAAAAAAAAA+1aXW/bNhT9KwQ3IFth2ZZsObYwDAVWDB3Wh2HD9tIEKUVdSawpUuVHErfwfx+oj8RO7MRR4nbJnIdApKR7eQ/PIXl99QV/r2kOBcERzo0pdTQYJJLqviSaaU+WIPpSZQNNFEub/+dB3+8PB1IP6ld13e/VLa+62/+opcA9rKzQOHr/BTNxLikxTDZtuARqXfMvSylonVqOI6MsLE97WIG23NQPzplIcIRTwjjuYQ7nwHGEQSmpXHvNKJcZo4S/W+sslSxBGQYaR1+wXhSx5Iy6ayKENNWTOMKEugvENBLSoJIJAQkyEhGUE52jHxR8skxBguIFijkRczCodJYWP+IensPCWXSeubvI2DmIs5KYHEe4P+hnzOQ2HlxINU+5vNAO5Dkor1T9ReECKxWk7NI9jJfLXhv1H4oVRC0ckNIacJapLEopQDTw/O4c448y1njZa5uxZTxZaWsDZX3/N5HAJY7863tWg8bL0+Vy6ZAvQGuSVY4MXJpH4rLs4TJf6NU5qXBXhqWEmtU+q5gL/h6clo4bWfMKiOQXyW0hcBSOeq75jgnAURD2sBasLMGsxIGaPxdvhN7KAmIFF4M6PD3QYGzp5U3364JoA8r509IqCu+IyGwFDF6QasK0Icq0/mdNux3AnsBUwImBZJXfTi2Ww2+OLVbUFr1qTnu4dEAT/isTGahSsYozThAVqVorbsxviXZEncbDJAj9gMZhks6COPIdGV+4Bg8C3EGAu6tv5H9j9Y38g/o6qY8SmgMCQWJeY5BASiw3KAcFz0xfwe76ujvsr6OgyWxVQeP7FdQKpxr865CMgE7HkKaTyTQch7Nwkib+dBgEfhjS8THMRhBMpuOuihp3xm6DZh5H0gwEKML5wgGRoIscBCptzJnOmchQOy8a1Q8aSBAxSFlhWLEvEv9ZB3kviaW4i4ePi+zr8NRf5enxJppKEZ0IhFqrZwnTJTE0r3pLq+sLhGJFBM0dld+jE1wQJk4wOq3v
    "workflow_run_id": 14824036933,
    "workflow_run_attempt": 1,
    "checkout_uri": "file:///home/runner/work/anubis/anubis",
    "environment": "null",
    "started_at": "2025-05-04T18:28:35.202Z",
    "tool_names": [
      "zizmor"
    ],
    "base_ref": "refs/heads/spell-check-with-spelling",
    "base_sha": "182b70882890702a5066c4[22](https://github.com/check-spelling-sandbox/anubis/actions/runs/14824036933/job/41614812126#step:5:23)db23758350de0ba4"
  }

As, this endpoint clearly requires permissions, the permissions should be documented as well. I'm pretty sure they're just security-events: write, but as I can't see the internals I can't claim that definitively.

Additional information

• [REST] Document /code-scanning/analysis/status #31331 asked about the internal API used by github/codeql-action, but I apparently missed the elephant in the room: /code-scanning/analysis

[jsoref]

It should also explain how this API differs from the /code-scanning/sarifs endpoint.

[jsoref]

For people curious about this endpoint, it uses PUT instead of POST. As with /repos/:owner/:repo/code-scanning/sarifs, when it's happy, it returns a 202. Unlike the /code-scanning/sarifs endpoint, it does not return a url field, although it still contains an id field which is still a sarif_id that can be used in /repos/:owner/:repo/code-scanning/sarifs/:sarif_id.

My current efforts to interoperate with this endpoint: check-spelling/check-spelling@c14a53d

[Sharra-writes]

Thanks for opening an issue! I'll get this triaged for review.

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[Sharra-writes]

@jsoref I heard back from our SMEs about this one, and they said it's like the issue you linked as additional information, where it's intentionally undocumented/not fully documented, because it's meant to be used internally.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.