Support Review Apps

[ghost]

Feature Request

Written from the perspective of a GitLab user

A user of a private instance of Read the Docs requested a nice-to-have feature: the ability to see the rendered form of a merge request that modifies a project's documentation.

It's a common practice for some project teams to involve non-developers in the documentation review process. The current best practice is to have contributors collaborate through the merge request process; a process that involves leaving comments on unrendered text (be that markdown or reStructuredText). Reviewing the rendered (and therefore structured) form of the content is just as crucial to ensuring high quality documentation as reviewing the text itself.

Therefore it would be beneficial if Read the Docs supported a Heroku-like feature called Review Apps in which the contents of a branch, submitted as a merge request, is built by Read the Docs, and posted to the merge request via the GitLab Commit Status API.

Read the Docs has support for GitLab webhooks tied to Push events, but that webhook support does not extend to merge request events.

The hook receiver could be extended to support the structure of a merge request event, but I believe the semantics of building documentation for a merge request will be different, as documentation generated from a merge request should be deleted upon the acceptance, or closing, of the merge request.

[agjohnson]

So, a similar integration is already on our roadmap for GitHub, #1340 -- we can leave these issues separate for now.

I took a swing at this already, the API integration is not the problem. The issue is in handling building of arbitrary versions, how to host them, and how to handle cloning of contributor repositories. I'll open a separate ticket here and shape up a milestone for these features. I'd like to see the GitHub integration first, GitLab and Bitbucket should be easy to implement after.

[agjohnson]

Blocked on #2465

[ghost]

Issue #1340 is exactly what I was looking for.

A note about fetching the contents of a merge request, GitLab exposes a ref for each merge request against a target repository.

Documentation here - https://gitlab.com/help/user/project/merge_requests.md#checkout-merge-requests-locally

It allows you to fetch the branch from the target repository, even if the source repository is private.

I believe GitHub has the same thing, though I've never tried either in practice.

[stsewd]

Isn't this the same as #1340 and #2465?

We have the feature in beta https://blog.readthedocs.com/building-docs-for-pull-requests/

[humitos]

They are the same to me. I think we can close it.