readthedocs / actions Goto Github PK

Hello! We are using this action to put the preview link in the PR, but it seems to fail when the PR was opened from a fork, see for example https://github.com/lab-cosmo/equistore/actions/runs/4325090692/jobs/7550783309.

It works fine when the PR branch is on the same repository, and we have permissions: pull-requests: write in our YAML file.
Is there anything we can do on our side?

The full error is

RequestError [HttpError]: Resource not accessible by integration
    at /home/runner/work/_actions/actions/github-script/v6/dist/index.js:6803:21
    at processTicksAndRejections (node:internal/process/task_queues:96:5) {
  status: 403,
  response: {
    url: 'https://api.github.com/repos/lab-cosmo/equistore/pulls/161',
    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: 'Fri, 03 Mar 2023 16:02:30 GMT',
      'referrer-policy': 'origin-when-cross-origin, strict-origin-when-cross-origin',
      server: 'GitHub.com',
      'strict-transport-security': 'max-age=31536000; includeSubdomains; preload',
      'transfer-encoding': 'chunked',
      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',
      'x-github-request-id': 'A041:5D7B:15B9E58:2CC4E11:64021A16',
      'x-ratelimit-limit': '1000',
      'x-ratelimit-remaining': '989',
      'x-ratelimit-reset': '1677860013',
      'x-ratelimit-resource': 'core',
      'x-ratelimit-used': '11',
      'x-xss-protection': '0'
    },
    data: {
      message: 'Resource not accessible by integration',
      documentation_url: 'https://docs.github.com/rest/reference/pulls/#update-a-pull-request'
    }
  },
  request: {
    method: 'PATCH',
    url: 'https://api.github.com/repos/lab-cosmo/equistore/pulls/161',
    headers: {
      accept: 'application/vnd.github.-preview+json',
      'user-agent': 'actions/github-script octokit-core.js/3.6.0 Node.js/16.16.0 (linux; x64)',
      authorization: 'token [REDACTED]',
      'content-type': 'application/json; charset=utf-8'
    },
    body: '{"body":"Fix #98 \\r\\n\\r\\n<!-- readthedocs-preview equistore start -->\\r\\n----\\n:books: Documentation preview :books:: https://equistore--161.org.readthedocs.build/en/161/\\n\\r\\n<!-- readthedocs-preview equistore end -->"}',
    request: { agent: [Agent], hook: [Function: bound bound register] }
  }
}

Ping @PicoCentauri

Can't support multiple language previews at once?
I think it would be nice to receive multiple arguments from the project language so that multiple links can be inserted.

I created the repository with readthedocs-preview, but that means that it is used as:

steps:
  - uses: readthedocs/readthedocs-preview@main

which repeats readthedocs. It is worth renaming it to something like:

• preview-url
• preview-links
• documentation-links
• pr-preview-links
• ....

Currently, the action only supports "Read the Docs Community". To support "Read for Business" we will need to think about:

• the combination of the project's slug + organization's slug
• the hard coded org.readthedocs.build domain

Reference: readthedocs/readthedocs.org#9450 (comment)

Hi,

I have a private project that uses readthedocs.com for building docs. I enabled previews by adding the following:

name: Read the Docs Pull Request Preview
on:
  pull_request_target:
    types:
      - opened

permissions:
  pull-requests: write

jobs:
  documentation-links:
    runs-on: ubuntu-latest
    steps:
      - uses: readthedocs/actions/preview@v1
        with:
          platform: business # I thought this would fix it but it didn't
          project-slug: slug

PRs are correctly triggering documentation preview but the generated link added in the top comment looks like this:

📚 Documentation preview 📚: https://slug--number.org.readthedocs.build/en/68/

I noticed that manually changing the .org -> .com fixes the issue:

📚 Documentation preview 📚: https://slug--number.com.readthedocs.build/en/68/

Am I doing something wrong or is this a bug?

It would be good to detect changes under certain directories (e.g. docs/) and only update the description in that situation. Example of a potential input for the action:

file-path:
  description: "Path where to check for file modifications"
  default: "docs/"
  required: false

Note we could use github.rest.pulls.listFiles to get the files changed in the PR:

const {data: pull_files } = await github.rest.pulls.listFiles({
    owner: context.repo.owner,
    repo: context.repo.repo,
    pull_number: context.issue.number,
});

for (let file of pull_files) {
    // do something here
}

When I try and add a github action following the steps outlined in https://github.com/readthedocs/actions/tree/v1/preview the autogenerated description preview links to a 404 error page.

On readthedocs.io I have Build pull requests for this project turned on, my project is public and the project slug is my project's slug on readthedocs.io. What could be causing this issue?

My github action looks like below:

name: readthedocs/actions
on:
  pull_request_target:
    types:
      - opened
    # Execute this action only on PRs that touch
    # documentation files.
    # paths:
    #   - "docs/**"

permissions:
  pull-requests: write

jobs:
  pull-request-links:
    runs-on: ubuntu-latest
    steps:
      - uses: readthedocs/actions/preview@v1
        with:
          project-slug: "my project slug"

This should probably be hitting our API to get an unresolved URL for the project, but for now, an option that is single_version or similar would be good. It's breaking the links in the WTD builds because we have a single_version there.

Currently we are installing it from main, but that means that it could be breaking changes. We should tag v1, so people can start using it at this simple state without worrying about us changing the behavior.

We could detect there were changes to specific files (via #3) and insert direct links to those documentation pages as well. For example, if the file docs/page/section.rst was modified, we could insert the link https://readthedocs-preview--1.org.readthedocs.build/en/1/pages/section.html

There are some notes to mention:

• we need to know where is the root directory that matches the root of the URL (in this case, we need to remove docs/ from the filename)
• the URL is a pretty URL (/pages/section/ or /pages/section.html)
• support user-configurable amount of links (with a small default), to avoid flooding in case of many files changed

Merging #16 will make us to do a release of the v1 again. We want to follow what we talked at #5 (comment)

This basically means re-tagging v1 to point to the latest commit that includes the single-version option.

Since this release process is no the common for other repositories, we need to document it in a clear way, so it's easy to follow.

I just tried this out for the first time here:

• simonw/sqlite-utils#460

The preview link it added didn't work, maybe because I have a custom domain setup?

It linked to: https://readthedocs-preview--460.org.readthedocs.build/en/460/ - which 404s

Here's the correct link: https://sqlite-utils--460.org.readthedocs.build/en/460/

My docs are hosted at https://sqlite-utils.datasette.io/ using a custom subdomain setup like this: https://til.simonwillison.net/readthedocs/custom-subdomain

Seems what the "readthedocs/actions/preview" action do is adding preview links to the pull request description. With certain "paths" configuration according to the documentation, even though the preview links will not be added, but it seems that the buld process is still triggerred. Any approach to disable the build process (to save resources)?

This is the case of our own repo https://github.com/readthedocs/readthedocs.org, where we have the docs and dev projects.

Currently, using the action more than once will override the previous comment

https://github.com/readthedocs/readthedocs-preview/blob/1029696f6a69477ff98e50ddb239e649f86ec384/action.yaml#L51

We should make the comment easier to locate, instead of using a plain ---- as separator, we could use a comment as a delimiter of the start/end of the comment. For example:

<!-- rtd-preview {project} start -->
Content
<!-- rtd-preview {project} end -->

That way, the current "separator" would be part of the template itself

---
:books: Documentation preview :books:: {docs-pr-index-url}

I've noticed the issue at python/docs-community#92, but it seems that other repos are affected as well.

When you type in :books: manually, it gets rendered:

Adding a space in the first emoji fixes the second emoji:

Using the emoji (📚) directly rather than using its name (:books:) might fix it!

Also, should these be concerning?

The action currently edits the PR description to add a separator and below that the links.

It would be good if we can also support adding a new comment the first time and after that update the comment with the newer links, if any. Then, the user could choose the approach that like the most.

Both approaches have pros/cons that is worth considering.

After merging #16 and releasing a new v1 in #17; it would be good to publish this action in the GitHub Marketplace so people can find it easily. I don't have experience about how it works, but it would be good to research a little.

https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace

Hello @humitos,

First of all, thank you for your work on actions 🙇🏻‍♂️

Sadly, now this repository looks abandoned.
I believe the community still need this repository to be maintained.
For instance, python/peps suffers from #34 while there is already a trivial fix #32.

I understand that you probably might have no time to deal with it right now, but would you mind considering delegating maintenance to some member of Read the Docs?

Thanks in advance!

Multiple times now, I've surprised myself and tried to click the check for the PR docs links action in the PR list of checks. Apparently I'm confused by how prominent the check looks, but of course the "details" link for that check does not do what you expect.

I'm actually not even sure where this name comes from, but just assuming its centrally configured here somehow.

So, I would say this first check is more prominent that our own RTD build check:

And even though our check has our icon in that list, I still somehow want to click the first check, the check for the links. So, if I am actively/subconsciously doing this as someone familiar with RTD, there must be others that would notice this.

Looking more at this, "Read the Docs" looks more official than "docs/readthedocs.com:...", and the first link mentions "pull request preview". Though the links are in the PR description, users are probably still used to clicking the check detail links, so would be bound to hit this confusion.

This is a case where showing this action in the PR action list is probably a worse scenario, but that's up to GitHub to deal with.

But because we shouldn't expect users to interact with this particular action in the list of checks, I think a much less prominent name would at least not overwhelm our actual PR check.

We could follow the naming scheme used in other checks, this is definitely less prominent and doesn't make me want to keep clicking it.

Suggestion

Instead of the RTD application always triggering its jobs, first check if in the commit there exists a github workflow that triggers readthedocs/actions/build (or whatever the name will end up being), and if it exists, do NOT trigger the default rtd workflow. Instead, have the action create an appropriate request to trigger it.

This is similar to dfm/rtds-action, but in that case it does not trigger the rtd workflow, it simply uploads the generated documentation. This action is intended to be much simpler, just to trigger the already present rtd workflow.

Benefit

• fine-grained control of when a RTD action is performed, e.g. only if docs folder is altered