In large companies, processes eventually take on a life of their own and start calling the shots. For us, the stumbling block was documentation publishing. Previously, technical writers would spend the entire month agonizingly collecting edits, only to push a single manual release out the door. That routine drove me up the wall. I wanted a proper CI/CD setup where everything builds itself after every push. But simply wanting it wasn't enough—I had to clearly prove to my colleagues that automation actually works in practice.
Transitioning to Static Site Generators (SSGs) required a Markdown parser. Our old internal tool could only spit out XML. Worse, on large codebases, it would grind to a complete halt for hours. Fortunately, while suffering through that, we had already put together a working Python ➡️ HTML pipeline (which I talked about in the previous part). All we had to do was hack it into Python ➡️ Markdown and start generating documentation for Flude itself. After all, the engine was also written in Python.
Next, infrastructure became the bottleneck. And that's when the corporate gears started grinding. Our Infrastructure Lead (the very guy who pitched the SSG idea) was buried under a mountain of tasks and then went on vacation. Sit and wait for his return just to fight for resources on the internal server? That meant putting the project on ice for at least a couple of months. So, I decided to go rogue.
The Escape Plan
If the internal network is off-limits, we take the experiment outside. GitHub fit the bill perfectly. I hid the engine's source code and the requirements list in private repositories. But the User Docs and the API Reference portals were quietly deployed in the cloud. At the end of the day, this was the open-source Flude. We weren't exposing a single line of proprietary corporate code.
Since we were building the project from scratch and for ourselves, we decided to experiment a bit. We picked completely different SSG frameworks for different portals. This complicated things slightly, but it was a great way to cut our teeth on configuring a diverse tech stack.
The pipeline architecture turned out exceptionally elegant. The User Docs portal automatically pulled fresh code from the closed repository. Then Flude woke up and parsed the source into Markdown on the fly. The SSG picked up the ready markup, built a static site out of it, and immediately pushed it to hosting (GitHub can serve HTML pages from public repos for free).
The Blind Architect
In theory, I understood the mechanics of CI/CD perfectly. The problem was purely practical: I didn't know the first thing about YAML syntax and had never configured GitHub Actions in my life. Just like when I started with Python, I was flying blind as an architect once again.
My AI teammate took over all the grunt work. I just described in plain English what should happen at each step. In return, the neural network spit out ready-made files for the .github/workflows folder. Sometimes it even slapped my wrist and forced me to implement best practices (like setting up dependency caching or splitting monolithic tasks into separate jobs). We pushed configs, stared at the red logs of failed builds, swore, fixed bugs, and ran it all over again.
The Moment of Truth
After a few evenings of non-stop tinkering, I made another push. GitHub Actions kicked into gear. The repository downloaded. Dependencies installed. Flude ran through the code, spitting out Markdown. The SSG instantly compiled the HTML. Deployment passed.
A green checkmark finally lit up on the screen. I clicked the site's URL and saw fresh documentation. It had updated itself, completely without my involvement.
At that moment, I screamed "Yes! Yes! Yes! It works!" so loudly that I scared my family, the budgies, and a couple of neighbors. It's an amazing feeling. Your concept just came to life right on the monitor. A routine monthly release just shrank down to a two-minute automated process.
We elegantly bypassed the corporate infrastructure, and the guerrilla pipeline was running like a well-oiled machine. But the final boss was looming ahead—legalizing the tool inside the company. We had to prove to the security department and management that our homegrown generator was just as good as the old standard. How do you run regression testing on closed data and make management believe in our parser? We'll cover that in the next episode.
Originally published on our blog: https://blog.flude.guide/blog/devops-on-github
Also read us:
