Opened 4 years ago

Last modified 3 years ago

#3459 new task

publish built on Travis docs for each pull request

Reported by: rutsky Owned by:
Priority: major Milestone: 0.9.+
Version: Keywords:


When PR considers formatting issues of documentation it would be really useful to be able to see built docs online.

For example developer changed chapters numbering in this PR — it would be convenient to see result without applying changes from PR locally.

I propose to setup public web-storage for recently built docs in pull requests, and to add step to .travis.yml that will upload built docs into that storage (so that built docs from PR will be available on the Internet).

Problems that need to be solved:

  1. Storage must be setup. Out of the box Travis support uploading on Amazon S3.
  1. Storage must authenticate requests on upload (auth data can be encrypted in .travis.yml).
  1. Storage must remove old builds (single html docs build occupies 8 megabytes).
  1. Cases when PR has unwanted content instead of docs should be considered. So it's better if storage will be on the separate domain from other Buildbot domains. And it should have ability to remove specific build.

Change History (11)

comment:1 Changed 4 years ago by dustin

I set up aliased at and created credentials which *should* have permission to upload to that bucket. Those credentials are installed into travis's env vars now. So this should be ready to put into .travis.yml.

comment:2 Changed 4 years ago by dustin

I set up a rule to delete the objects in the bucket 2 weeks after they are created.

The bucket is under my AWS account.

comment:3 Changed 4 years ago by rutsky

PR should fix this issue.

Lets wait till it finish building, but here is one of the tests:

comment:4 Changed 4 years ago by dustin

It says in that PR that artifact support is disabled for PRs -- did that just change?

The test link doesn't appear -- did it expire already?

comment:5 Changed 4 years ago by rutsky

I believe I saw working artifacts uploading during my tests because I pushed into branch in Buildbot, not because there was PR with that branch.

AFAIK, Travis runs tests for pushes in branches too, so all worked while my branch were build in "branch" mode. At some point Travis decided that it should build not in "branch mode", but in "PR mode", and in PR mode artifacts doesn't work.

comment:6 Changed 4 years ago by rutsky

I think not working artifacts in PR is a security feature: looks like private environment variables like ARTIFACTS_SECRET are actual environment variables during all steps that run inside Travis VM, so malicious can add step like echo $ARTIFACTS_SECRET in his PR to steal credentials.

Looks like AppVeyor allows artifacts upload for pull requests: but they don't decrypt secret env. variables in PRs, so there is no way to use it in PRs without exposing credentials.

comment:7 Changed 4 years ago by dustin

So it sounds like this is impossible? Should I back out my AWS setup?

comment:8 Changed 4 years ago by rutsky

So it sounds like this is impossible?

To securely build and publish docs for all PR with Travis/AppVeyor? — looks like yes, it's impossible. Still we can build docs for Buildbot branches, so at least core developers would be able to benefit of this feature, but this is significantly less than original goal of this issue.

Should I back out my AWS setup?

Yes, thanks for testing!

P.S. Regarding "branch" vs "PR" modes: Travis run both for branches in Buildbot. They can be distinguished by label: continuous-integration/travis-ci/pr and continuous-integration/travis-ci/push. And or build in continuous-integration/travis-ci/push docs are published in my latest test:

comment:9 Changed 4 years ago by rutsky

Publishing docs with Circle CI should be done in

comment:10 Changed 4 years ago by rutsky

In general this issue is resolved: Circle CI builds docs and they can be reached in build artifacts tab if user is logged in into Circle CI (GitHub? account is sufficient).

However it would be nice to have direct link to docs explicitly attached to PR, for example as build status. This can be achieved by setting up bot that will receive Circle CI web hook about finished build and posting GitHub? status update for commit.

Note: See TracTickets for help on using tickets.