How we Auto-Deploy Documentation Pull Requests with Platform.sh

Symfony's documentation is an open source project with more than 800 contributors. That’s great! But our goal is to always make it easier to contribute and faster to merge in changes. And today, we’ve started doing something really cool to improve our workflow: integration with Platform.sh.

Platform.sh is a hosting solution that provides out-of-the-box continuous deployment for Symfony, Drupal and any other PHP applications. It extends the concept of a Git branch at the infrastructure level. Basically, this means that it’s easy to deploy every branch and/or Pull Request to its own URL.

Symfony's documentation is written in Sphinx (Markdown on steroids) with linking, complex code blocks and more. That gives us a lot of flexibility, but also causes 2 major problems:

• When someone makes a pull request to the docs, they can't immediately see how it will render.

• It's tough to review, since it takes too much time for a reviewer to pull down the branch, compile it locally, then open it up in a browser.

The problem is shared with any real coding projects: when you finish a feature, you then need to manually deploy it to a server before it can be reviewed and tested.

But what if each pull request could be automatically deployed to its own server with its own URL?

This is something we've wanted for a long time… That’s why we were thrilled when Platform.sh approached us and said "Yeah, that's easy to do!".

So, as of today, I’m excited to say that the Symfony documentation is the first open source project (we know of at least) that automatically builds and deploys any code change from any contributor into an isolated environment with its own URL, so it can easily be reviewed and tested. Boom!

For example, Pull Request #5530 documents an entire new feature. By simply clicking "Details" next to the "platformsh" check on the bottom, we can review this pull request in its true HTML format.

You see that there is a URL provided by Platform.sh and including the http://pr-5530-6qmocelev2lwe.eu.platform.sh/

How is the madness possible?

First, Platform.sh was awesome enough to setup our environment for free! If you see them on Twitter or at a conference, give them a big thank you!

Second, the only thing required to integrate with Platform.sh is to add a configuration file called .platform.app.yaml in your repository which describes how the code should be built - similar to .travis.yml. That - and a GitHub webhook - were enough to start automatically deploying pull requests. Third, WouterJ (core docs contributor) created a symfony.com-like theme to make the previews as realistic as possible.

So, next time you make a pull request to the docs, check out how it looks!