Here is how the OpenShift docs preview bot works.

I am a tech writer and passionate about automation. When I joined the OpenShift documentation team and RedHat, I saw many opportunities for automating some day-to-day tasks. During my time there, I created various scripts and programs and automated multiple docs-workflow tasks. However, creating a documentation preview bot for OpenShift documentation was both challenging and fun.

TL;DR — beep bop

Every pull request on the OpenShift docs repository triggers Travis CI check. On completion of the OpenShift docs Travis CI check, it sends a request to a web server running on Glitch. The web server verifies the request and sends a webhook to the OpenShift docs preview bot Travis CI. The OpenShift docs bot Travis CI pull the original pull request, pushes as a new branch on the OpenShift docs preview bot repository, and adds a comment on the original pull request including the preview build URL. Netlify gets the new branch from the OpenShift docs preview bot repository and builds a docs preview site.

The backstory

For writing OpenShift documentation, we use AsciiDoc markup and build the documentation site using AsciiBinder. We use GitHub to host the docs repository and use Pull requests to make changes to the docs. But before we merge these requests and publish changes, we get approvals from multiple stakeholders, including developers and testing teams. For minor changes, it was always easy to review everything in GitHub, but for more significant changes, or moving content around, changing names and other similar tasks, the process was a little bit dated.

Along with the changes, it was writers task to:

1. Generate a preview documentation website locally.
2. Upload it to a file server.
3. Add the link to this uploaded preview documentation site to the GitHub pull request.

I saw an opportunity to improve this workflow, there are already tools available for handling this automatically like Netlify. So I tested Netlify with my fork of the OpenShift docs repo, and it worked as I intended. Therefore I went back to the team (and project administrators) and asked them to enable Netlify for automatic documentation preview builds. But since Netlify requires GitHub permissions on the repository, I got my request denied.

That was a setback, but it led me thinking about workarounds to accomplish this.

After looking for different ways to make it work, trials, errors, and learning, I settled on the following workflow:

I started by creating a new GitHub account for OpenShift docs preview bot and forked the OpenShift docs repo using this account. I also integrated this bot account with Travis CI and Netlify. Here is how everything comes together.

1. OpenShift docs repo includes a Travis CI check, which runs on every pull request. I hooked a script into the Travis CI config file which runs only if Travis CI check passes.
2. The Travis CI script checks if a pull request triggered the Travis CI build and sends a web request to a custom Web server running on Glitch.
3. The Glitch sever verifies the request and sends a webhook to the Travis CI instance of OpenShift docs preview bot. This request overrides the original Travis CI configuration.
4. The OpenShift docs preview bot Travis CI first downloads the original pull request for the OpenShift docs repo, sync bot’s repo master with upstream master, pushes the pull request as a new branch to the OpenShift docs preview bot repo, and adds a comment on the original pull request.
5. The OpenShift docs preview bot repository is connected to Netlify and alerts Netlify about the incoming changes.
6. Netlify creates and deploys a new preview site for the added branch.

If you want to dig deeper into the actual scripts, custom web server code, and other related information feel free to check out following resources:

1. OpenShift docs Travis CI script: https://github.com/openshift/openshift-docs/blob/master/autopreview.sh
2. Travis CI sample build log: https://travis-ci.com/openshift/openshift-docs/builds/116493941#L667
3. Glitch webhook receiver and sender: https://glitch.com/~preview-receiver
4. OpenShift docs preview bot Travis CI script: https://github.com/gaurav-nelson/scripts/blob/master/push_to_netlify.sh
5. Preview bot Travis CI sample build log: https://travis-ci.com/openshift-docs-preview-bot/openshift-docs/builds/116494069
6. Netlify build script: https://github.com/gaurav-nelson/scripts/blob/master/ocp_preview.sh

Once I got everything working, my plan was to include some documentation tests like hyperlink, spelling, document structure and other checks into the OpenShift docs preview bot Travis CI script. You might see verbiage of that if you go through these scripts.

Why didn’t it happen already? Maybe I’ll talk about that in some other blog post. 😀