[DOCS]: Incorrect reference qualification for `octokit.rest.git.updateRef`

qubitz commented 1 year ago

Describe the need

The documentation for octokit.rest.git.updateRef() should correct its requirement of a fully qualified reference. After some iterations trying to use this endpoint, I discovered that fully qualified tag references resulted in "Reference does not exist" response errors.

The documentation currently describes the ref parameter as:

The name of the fully qualified reference to update. For example, refs/heads/master. If the value doesn't start with refs and have at least two slashes, it will be rejected.

Based on limited testing, it seems that it should be renamed to something along the lines of:

The name of the fully qualified reference to update without the ref/ prefix. For example, heads/master or tags/latest. If the value does includes the ref/ suffix, the reference will not be found.

Further testing is needed to see if it applies to similar endpoints. Happy to help in this regard if there is interest.

Similar issues:

SDK Version

actions/github-script@v6

API Version

v19

Relevant log output

RequestError [HttpError]: Reference does not exist
    at d:\dev\github\_work\_actions\actions\github-script\v6\dist\index.js:6842:21
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at async Job.doExecute (d:\dev\github\_work\_actions\actions\github-script\v6\dist\index.js:7588:18) {
  status: 422,
  response: {
    url: 'https://api.github.com/repos/xxxx/xxxxxxxxxxx/git/refs/refs%2Ftags%2Flatest',
    status: 422,
    headers: {
      'access-control-allow-origin': '*',
      'access-control-expose-headers': 'ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset',
      connection: 'close',
      'content-length': '122',
      'content-security-policy': "default-src 'none'",
      'content-type': 'application/json; charset=utf-8',
      date: 'Mon, 17 Jul 2023 17:31:52 GMT',
      'referrer-policy': 'origin-when-cross-origin, strict-origin-when-cross-origin',
      server: 'GitHub.com',
      'strict-transport-security': 'max-age=31536000; includeSubdomains; preload',
      vary: 'Accept-Encoding, Accept, X-Requested-With',
      'x-content-type-options': 'nosniff',
      'x-frame-options': 'deny',
      'x-github-api-version-selected': '2022-11-28',
      'x-github-media-type': 'github.v3; format=json',
      'x-github-request-id': 'D668:560E:D9FBE1:1B96151:64B57B08',
      'x-ratelimit-limit': '15000',
      'x-ratelimit-remaining': '14997',
      'x-ratelimit-reset': '1689618711',
      'x-ratelimit-resource': 'core',
      'x-ratelimit-used': '3',
      'x-xss-protection': '0'
    },
    data: {
      message: 'Reference does not exist',
      documentation_url: 'https://docs.github.com/rest/reference/git#update-a-reference'
    }
  },
  request: {
    method: 'PATCH',
    url: 'https://api.github.com/repos/xxxx/xxxxxxxxxxx/git/refs/refs%2Ftags%2Flatest',
    headers: {
      accept: 'application/vnd.github.v3+json',
      'user-agent': 'actions/github-script octokit-core.js/3.6.0 Node.js/16.16.0 (win32; x64)',
      authorization: 'token [REDACTED]',
      'content-type': 'application/json; charset=utf-8'
    },
    body: '{"sha":"75798c0d52e00834f6f5a9e5c3b0bb9eb204f65a","force":true}',
    request: {
      agent: [Agent],
      retries: 2,
      hook: [Function: bound bound register],
      retryCount: 2
    }
  }
}
Error: Unhandled error: HttpError: Reference does not exist

Code of Conduct

[X] I agree to follow this project's Code of Conduct

wolfy1339 commented 1 year ago

This isn't something we can change ourselves, as the endpoints are auto-generated from GitHub's OpenAPI spec.

To get this fixed, open an issue on their repo: https://github.com/github/rest-api-description/

qubitz commented 1 year ago

Thanks for the quick response @wolfy1339, that makes a lot of sense. I transferred the issue to https://github.com/github/rest-api-description/issues/2746

wolfy1339 commented 1 year ago

Let's keep this open for tracking on our side

octokit / octokit.js