A (better) workflow with Kirby and Git

This blog entry is older than a year. Some things might be out of date by now.

Yes, I've already written about this topic in early 2016, but recently I've migrated this blog to a new server (hello again, Uberspace) and therefore I had the chance to get rid of the waste. One of the things I've wanted to improve is the connection between me as the editor and the server. Even if the previous implementation was based on Git it was rather poorly implemented. I knew I wanted to improve this workflow, since it was one of the things that kept me away from writing. So I've searched around in the interwebz and found a new way to a version-controlled homepage, which I want to share with you :)

The new way is based on three amazing things: GitHub, the Auto Git Kirby plugin by Pedro Borges and webhooks.

But let's start from the beginning.

Step 1: Create the repository

I wanted to start from scratch for my personal website, so at the beginning I've downloaded the Kirby Starterkit. To be honest, I'm not that guy that knows CSS & JavaScript very well, so I'm always thankful if there's a base I can build on.

After the extraction of the archive I removed the kirby and the panel folder. You may be asking why, since it's the core application? Well, I wanted to add it as a submodule, so future updates from Kirby can be done by executing the following command:

git submodule foreach git pull origin master

Yes, I know, there exists the Kirby CLI, but for a task that I am executing only from time to time, I don't want to add another dependency, Composer in this case. But let's head back to the tutorial. Before you can add the submodules, the git repository must be initialized with git init. Now there should be a folder structure like the following:

├───.git (hidden folder)

To add both the Kirby core and it's panel to the repository, execute the following commands:

git submodule add https://github.com/getkirby/kirby
git submodule add https://github.com/getkirby/panel

Well, the repository is now just on the local machine, which is useless. So in the next step, you should create a blank repository on one of the public Git websites out there, I've personally chosen GitHub since I'm very familiar with it. Each service has is own way of publishing the code, but in general it will look like this:

git remote add origin git@github.com:jlnostr/studious-fiesta.git
git push -u origin master

Step 2: Configure Auto Git

The most important piece in this setup is the Auto Git Kirby plugin by Pedro Borges. It will make the future bright and I'm not exaggerating there. Each change you perform via the panel is automatically committed, so everything can be tracked at a later time. The most interesting feature of Auto Git are the webhooks mentioned in the introduction. So, when you push to the repository, GitHub will notify your website so it fetches the newest content automatically.

In this tutorial I also add Auto Git as a submodule. So by executing the following code in your website's root folder, you've installed it.

git submodule add https://github.com/pedroborges/kirby-autogit.git site/plugins/autogit
git submodule update --init --recursive
git commit -am "Add Auto Git plugin to Kirby."

To enable the webhook feature, add the following line to your site/config/config.php:

c::set('autogit.webhook.secret', myRandomString);

Replace myRandomString with something very long and random.

Step 3: Checkout the repo from the server

Once logged in into your server, navigate to the DocumentRoot. In the case you're using an Uberspace like me, this folder will be located at /var/www/virtual/$USER/html. Because Git creates a new folder for the checkout, I've removed the html folder and invoked the checkout the following way:

git clone https://github.com/jlnostr/studious-fiesta.git html

Beware: This makes the .git folder and therefore each commit available to everyone! You might not want this, so consider adding the following lines to the .htaccess file:

# Hide git-related files
RedirectMatch 404 /\.git

This will tell everyone out there, who's trying to access git-related files that they are simply not here.

Step 4: Configure webhooks

Now we're coming to the interesting bits! To configure the webhooks, open the webhook settings page on your Git provider. Add a new webhook that's going to be invoked only on the push event (default on GitHub). I've made a screenshot of how this looks like in my case. The asked secret is the myRandomString you've replaced earlier.

My webhook configuration as seen on GitHub

GitHub will automatically test the webhook, so you'll notice at a glance if everything was configured the right way. If this is the case, then I welcome you to a world full of automatism. Yep, we're done at this point.

From now on, when you change something on your homepage via the panel, a commit is created, changes on the Git repository are automatically fetched and everything stays in sync. Plus, you have the benefits of git, including branching, an unlimited history, pull requests and so on.

How publishing works with this workflow

My personal workflow now looks like the following way:

  • Create a new branch
  • Write the first draft of the article
  • Commit this draft
  • Finish the article at a later time (spell corrections, clarifications, etc.)
  • Commit these changes
  • When finished: View the article in the browser on a local Kirby instance
  • Fix possible artefacts, wrong aligned images, etc.
  • Rebase and merge into master

The merge commit then invokes the webhook, which updates my homepage. Voila! All I needed was a simple git push.

In case you have any questions or feedback, just leave it in the comment section below :)