Automatically add readthedocs preview links to PR descriptions

[sgibson91]

This PR adds a GitHub Action workflow that will automatically add readthedocs preview link to Pull Request descriptions, making viewing rendered changes more accessible. An example PR is here: https://github.com/sgibson91/test-multilingual-sphinx/pull/4

[sgibson91]

Tbh, I'm surprised the workflow ran at all in this PR. I thought workflow files needed to be on the default branch before they could be triggered - unless something in GitHub Actions has changed.

I double checked that PR builds were enabled in readthedocs (which they were) and then pushed a commit that made the permissions block workflow-level instead of job-level. Which tbh I don't think should make a difference, but it now more closely matches the workflow file I have in my example which "just worked".

I think I will also add types: [reopened] so that I can retest this PR with the new changes.

[sgibson91]

I do not understand why this is failing. Seemingly from the logs it is failing on a PATCH request to the Pull Request, and I believe the pull-requests: write permission should cover this use case.

RequestError [HttpError]: Resource not accessible by integration
    at /home/runner/work/_actions/actions/github-script/v6/dist/index.js:6842:21
    at processTicksAndRejections (node:internal/process/task_queues:96:5) {
  status: 403,
  response: {
    url: 'https://api.github.com/repos/2i2c-org/docs/pulls/194',
    status: 403,
    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-encoding': 'gzip',
      'content-security-policy': "default-src 'none'",
      'content-type': 'application/json; charset=utf-8',
      date: 'Tue, 14 Nov 2023 14:30:44 GMT',
      'referrer-policy': 'origin-when-cross-origin, strict-origin-when-cross-origin',
      server: 'GitHub.com',
      'strict-transport-security': 'max-age=3[153](https://github.com/2i2c-org/docs/actions/runs/6865056396/job/18668175871?pr=194#step:2:163)6000; includeSubdomains; preload',
      'transfer-encoding': 'chunked',
      vary: 'Accept-Encoding, Accept, X-Requested-With',
      'x-accepted-github-permissions': 'pull_requests=write',
      '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': '4C43:99EF:361A29:6F5C28:65538494',
      'x-ratelimit-limit': '1000',
      'x-ratelimit-remaining': '998',
      'x-ratelimit-reset': '1699975844',
      'x-ratelimit-resource': 'core',
      'x-ratelimit-used': '2',
      'x-xss-protection': '0'
    },
    data: {
      message: 'Resource not accessible by integration',
      documentation_url: 'https://docs.github.com/rest/pulls/pulls#update-a-pull-request'
    }
  },
  request: {
    method: 'PATCH',
    url: 'https://api.github.com/repos/2i2c-org/docs/pulls/194',
    headers: {
      accept: 'application/vnd.github.v3+json',
      'user-agent': 'actions/github-script octokit-core.js/3.6.0 Node.js/16.20.2 (linux; x64)',
      authorization: 'token [REDACTED]',
      'content-type': 'application/json; charset=utf-8'
    },
    body: '{"body":"This PR adds a GitHub Action workflow that will automatically add readthedocs preview link to Pull Request descriptions, making viewing rendered changes more accessible. An example PR is here: https://github.com/sgibson91/test-multilingual-sphinx/pull/4\\r\\n\\r\\n<!-- readthedocs-preview 2i2c-pilot-documentation start -->\\r\\n----\\n:books: Documentation preview :books:: https://2i2c-pilot-documentation--[194](https://github.com/2i2c-org/docs/actions/runs/6865056396/job/18668175871?pr=194#step:2:204).org.readthedocs.build/en/194/\\n\\r\\n<!-- readthedocs-preview 2i2c-pilot-documentation end -->"}',
    request: { agent: [Agent], hook: [Function: bound bound register] }
  }
}

[sgibson91]

I can no longer get this workflow to trigger in the PR context, so I'm just going to merge it and see what happens. I can revert it if it doesn't work.

[sgibson91]

Hooray! 🎉 https://github.com/2i2c-org/docs/pull/196 I'll go and tidy up the other PRs now

[damianavila]

Nice to see it worked!