In a previous article, we have set up a testing environment for our documentation website built with Sphinx. What we want to do right now is to deploy the documentation “on demand” for each contribution done on GitHub.
The advantage is to allow everyone to review the UI of a new contribution, and ensure that the website is built the right way in a real environment.
At Akeneo, we have chosen to use Platform.sh and they kindly accepted to sponsor the Akeneo documentation. Thank you, guys :)
Set up a Platform.sh environment
First of all, create an account on Platform.sh using the “Free Trial” button on the homepage: for one month you can access three development platforms. From our tests, it’s enough for little needs but Platform.sh team recommends using at least the “small” platform if you require going into production.
After account creation and the selection of the platform, you should see the project configurator form.
Select a name for our project and continue to the next screen.
Now we have the choice between creating a blank template or importing our project: as we already have a project on GitHub, we select this option.
Except if you have created your account using GitHub credentials, a new form input asks you to fill an SSH key. If you don’t know what it is or how it works, take a look at GitHub documentation. Doing this, we allow Platform.sh to manage your Git repositories.
At this point, Platform.sh reminds you that you need to add configuration files to your project:
.platform.app.yaml. Let’s see together what are theses files.
Configure your application
You control your application and the way it will be built and deployed on Platform.sh via one single configuration file,
.platform.app.yaml, located at the root of your application folder inside your Git repository.
Applications have multiple properties to define the environment to deploy, the disk space, the dependencies and much more. The official documentation describes everything you need to configure your platform.
For instance, this is the application file for the Akeneo documentation project:
We have defined the environment (Python 2.7), the dependencies and the web/public folder available from a web browser. The interesting part is the
hooks section where we describe how to build the application: we install Sphinx and the required extensions. The generation of the documentation is done into the folder configured in the
Add routes to your application
When Platform.sh is used in a Web/HTTP context, you need to declare routes to make the application available from a web browser.
The configuration of routes documentation is accessible on Platform.sh website. For instance, this is the routing file for the Akeneo documentation project:
The most important point to not forget is the “akeneodocs” value in
upstream is the application name declared in
Add services to your application
We didn’t need any of them for your documentation, but you can find information in the dedicated Services section of documentation.
services.yaml file must be present, our own only contains a comment to explain that the file needs to exist.
Now we can return to the Project configurator assistant:
The first time you push your git project to the Platform.sh remote, a build is done: if the configuration files are invalid, you will see an error message.
The configuration files must be present on the pushed branch of your Git repository.
For Akeneo documentation project, this is what we have seen on first push:
And inside the Platform.sh application, you can see that a first build has been done on the master branch:
From the interface you can access the documentation website: YAY!
At this moment, every time you will update or push a branch to Platform.sh, this will start a new build that produces a website available from an url. But you probably don’t want to share the credentials of Platform.sh with everyone from your community do you? Here comes the integration with GitHub!
GitHub + Platform.sh = great contribution workflow
Remember what we wanted in the previous article: to be able to provide a link to the documentation website for a the selected pull request directly into the GitHub interface.
The GitHub integration allows you to manage your Platform.sh environments directly from your GitHub repository.
This is what you can do right now:
- Create a new environment when creating a branch or opening a pull request on GitHub;
- Rebuild the environment when pushing new code to GitHub;
- Delete the environment when merging a pull request.
Let’s set up the GitHub integration of our documentation project.
Get a GitHub token
The creation of tokens is easy and the documentation is available on Github.
The token needs to have
If your repository is private, you must add additional scopes:
repo (i.e all items from
repo scope) and
read:org (if the repository is owned by an organization).
The token must be created by an account who have push access on repository.
Enable the GitHub integration using Platform cli
First of all, install the platform cli application. On GNU/Linux and MacOS X you can get it using this command:
curl -sS https://platform.sh/cli/installer | php
The first time you launch the application, you need to login with your Platform.sh credentials:
You can now add a GitHub to the project using this command:
If you enable
fetch-branches option, Platform.sh will get all branches of your repository and will try to build them, even the branches that don’t come from pull requests.
The most important information is the
hook_url value, because this is the url endpoint you need to set up into GitHub weebhook menu.
Final step, Add the GitHub webhook
Creating a new weebhook on GitHub is really easy:
It is important that you chose
application/json as Content type and to send everything to Platform.sh.
Once enabled, every new pull request on your repository will be handled by Platform.sh and will produce a link with the build.
At Akeneo we really enjoy this new process and we plan to also use Platform.sh or Jenkins to deploy the documentation to make the contribution workflow even easier!
If you want to share your ideas and your development/contribution workflow, use the comment form :)