DEV Community

cosckoya
cosckoya

Posted on

Mkdocs automate CI/CD with Github actions

I'm developing my own mkdocs as a personal wiki. I've been working as a system engineer for 10 years and I have a lot of notes, cheats, scripts and tips on my laptops. And it's been a mess to look for some of them when I really needed. That's because I started a mkdocs project :)

I've been working on it, installing all the pip packages manually, testing the builds and then publishing into github pages. One time, and another, and another the same repetitive task. So I've managed a Github action to publish the mkdocs in Github pages automatically.

But, what's Github actions? GH Actions are a feature that allows anyone to generate a CI/CD pipeline into your own git repository with no need to manage Jenkins, TravisCI or any other engine to realize that.

As you create a Github repository, you're able to create "Actions" just clicking on the project menu, then it will show you a set of different predefined actions or create a blank one. I created one from scratch:

 name: mkdocs

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [ 3.8 ]

    steps:
      - uses: actions/checkout@v2

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
          architecture: x64

      - name: Install requirements
        run: python3 -m pip install -r requirements.txt

      - name: Deploy 🚀
        run: python3 -m mkdocs gh-deploy --force
Enter fullscreen mode Exit fullscreen mode

This job is run when a commit or pull request is merged in the "main" branch, then it creates an Ubuntu agent with a matrix of different Python version; in here I only use Python v3.8; then it installs all the pip packages declared in the "requirements.txt" file and then runs the mkdocs command "gh-deploy" that builds and deploy the mkdocs project in the "gh-pages" branch.

Now I only have to commit my local changes into the "main" branch and Github deploys everything for me :P

Enjoy!

Top comments (0)