How can simplify your contribution workflow on GitHub website homepage

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 and they kindly accepted to sponsor the Akeneo documentation. Thank you, guys :)

Set up a environment

First of all, create an account on 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 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 to manage your Git repositories.

At this point, reminds you that you need to add configuration files to your project: .platform/services.yaml.platform/routes.yaml and 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 via one single configuration file,, 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 web/locations section.

Add routes to your application

When 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 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 file.

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.

The 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 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 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, 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 with everyone from your community do you? Here comes the integration with GitHub!

GitHub + = 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 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 public_repo scope:

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 | php

The first time you launch the application, you need to login with your credentials:

You can now add a GitHub to the project using this command:

If you enable fetch-branches option, 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

Once enabled, every new pull request on your repository will be handled by and will produce a link with the build.

And now everyone can access the website built from this contribution: isn’t AMAZING?

At Akeneo we really enjoy this new process and we plan to also use 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 :)

Happy hacking!