DIY CI

Do-It-Yourself Continuous Integration

This page covers notes on creating a homebrew continuous integration server.

Documentation Builds

The first example we focus on here is building documentation.

The Scenario

The scenario is, we have multiple repositories full of markdown documents, and we want to build them into a single static site using mkdocs.

We create each repository full of markdown files. Then we create a master www repository that is set up like a normal mkdocs repository - it has an mkdocs.yml file, a docs/ folder, and an mkdocs theme, and it builds the documentation into site/.

In the docs/ folder, each repository with markdown files is set up as a submodule of the main www repository. In this way, changes to the markdown files in those repositories will be automatically reflected in the parent www repository.

To build the docs, we just run the mkdocs command. This builds the documentation into site/.

The workflow

What is the workflow that we want?

In the documentation repositories full of markdown files:

• Users will create a branch, edit documents, create a pull request
• Pull requests are reviewed and merged into master when ok
• When a pull request is open, there should be functionality to apply markdown cleanup (and also to keep making modifications, i.e., to reverse any changes)

In the www repository:

• When changes are pushed to master branch of any submodule:
  • update submodule
  • rebuild site
  • redeploy site

Infrastructure

Markdown bot:

• waits for a mention
• when a mention is made, it will apply markdown cleanup (but ONLY to files changed in the given pull request)

Captain Hook:

• flask hook server running in container
• listens for incoming web hook
• hook scripts will:
  • clone private www
  • update the submodule and commit
  • clone site/
  • build site/
  • deploy site/ (optionally, to heroku)