Nikola (Posts about automation)

Automating Nikola rebuilds with GitHub Actions

Chris Warrick — Fri, 24 Apr 2020 22:24:48 GMT

In this guide, we’ll set up GitHub Actions to rebuild a Nikola website and host it on GitHub Pages.

Why?

By using GitHub Actions to build your site, you can easily blog from anywhere you can edit text files. Which means you can blog with only a web browser and GitHub.com. You also won’t need to install Nikola and Python to write. You won’t need a real computer either — a mobile phone could probably access GitHub.com and write something.

Caveats

The build might take a couple minutes to finish (1:30 for the demo site; YMMV)
When you commit and push to GitHub, the site will be published unconditionally. If you don’t have a copy of Nikola for local use, there is no way to preview your site.

What you need

A computer for the initial setup that can run Nikola. You can do it with any OS (Linux, macOS, *BSD, but also Windows).
A GitHub account (free)

Setting up Nikola

Start by creating a new Nikola site and customizing it to your liking. Follow the Getting Started guide. You might also want to add support for other input formats, namely Markdown, but this is not a requirement.

After you’re done, you must configure deploying to GitHub in Nikola. There are a few important things you need to take care of:

Make your first deployment from your local computer and make sure your site works right. Don’t forget to set up .gitignore.
The GITHUB_COMMIT_SOURCE and GITHUB_REMOTE_NAME settings are overridden, so you can use values appropriate for your local builds.
Ensure that the correct branch for GitHub Pages is set on GitHub.com.

If everything works, you can make some change to your site (so you see that rebuilding works), but don’t commit it just yet.

Setting up GitHub Actions

Next, we need to set up GitHub Actions. This is really straightforward.

On your source branch, create a file named .github/workflows/main.yml with the following contents:

github-workflow.yml (Source)

	`on: [push]`

	`jobs:`
	`nikola_build:`
	`runs-on: ubuntu-latest`
	`name: 'Deploy Nikola to GitHub Pages'`
	`steps:`
	`- name: Check out`
	`uses: actions/checkout@v2`
	`- name: Build and Deploy Nikola`
	`uses: getnikola/nikola-action@v2`

There might be a newer version of the action available, you can check the latest version in the getnikola/nikola-action repo on GitHub.

By default, the action will install the latest stable release of Nikola[extras]. If you want to use the bleeding-edge version from master, or want to install some extra dependencies, you can provide a requirements.txt file in the repository.

Commit everything to GitHub:

git add .
git commit -am "Automate builds with GitHub Actions"

Hopefully, GitHub will build your site and deploy. Check the Actions tab in your repository or your e-mail for build details. If there are any errors, make sure you followed this guide to the letter.

Automating Nikola rebuilds with Travis CI

Chris Warrick — Wed, 24 Aug 2016 18:05:25 GMT

In this guide, we’ll set up Travis CI to rebuild a Nikola website and host it on GitHub Pages.

Why?

By using Travis CI to build your site, you can easily blog from anywhere you can edit text files. Which means you can blog with only a web browser and GitHub.com. You also won’t need to install Nikola and Python to write. You won’t need a real computer either — a mobile phone could probably access GitHub.com and write something.

Caveats

The build might take a couple minutes to finish (1:30 for the demo site; YMMV)
When you commit and push to GitHub, the site will be published unconditionally. If you don’t have a copy of Nikola for local use, there is no way to preview your site.

What you need

A computer for the initial setup that can run Nikola and the Travis CI command-line tool (written in Ruby) — you need a Unix-like system (Linux, macOS, *BSD, etc.); Windows users should try Bash on Ubuntu on Windows aka Windows Subsystem for Linux (available in Windows 10 starting with Anniversary Update) or a Linux virtual machine.
A GitHub account (free)
A Travis CI account linked to your GitHub account (free)

Setting up Nikola

After you’re done, you must configure deploying to GitHub in Nikola. There are a few important things you need to take care of:

Make your first deployment from your local computer and make sure your site works right. Don’t forget to set up .gitignore (We’ll add two very important entries later.)
You must set GITHUB_COMMIT_SOURCE = False — otherwise, Travis CI will go into an infinite loop.
We assume your source branch is src and you deploy to master. Any other configuration requires editing .travis.yml.
We enable builds only for the src branch by default. Older versions of the script did not include this provision, and thus committing to master (which you should not do, as your changes will be overwritten on next Travis rebuild) used to cause Rakefile errors.

If everything works, you can make some change to your site (so you see that rebuilding works), but don’t commit it just yet.

Setting up Travis CI

Next, we need to set up Travis CI. To do that, make sure you have the ruby and gem tools installed on your system. If you don’t have them, install them from your OS package manager.

First, download/copy the .travis.yml file (note the dot in the beginning; the downloaded file doesn’t have it!) and adjust the real name, e-mail (used for commits; line 15/16), and the username/repo name on line 24. If you need any other Python/apt packages to build your site, add them to your config. (For apt packages, you will need addons: apt: packages: keys.)

travis.yml (Source)

	`# Travis CI config for automated Nikola blog deployments`
	`language: python`
	`cache: apt`
	`sudo: false`
	`branches:`
	`only:`
	`- src`
	`python:`
	`- 3.6`
	`before_install:`
	`- git config --global user.name 'Travis CI'`
	`- git config --global user.email 'travis@invalid'`
	`- git config --global push.default 'simple'`
	`- pip install -U --upgrade-strategy=eager pip setuptools wheel`
	`- echo -e 'Host github.com\n StrictHostKeyChecking no' >> ~/.ssh/config`
	`- eval "$(ssh-agent -s)"`
	`- chmod 600 id_rsa`
	`- ssh-add id_rsa`
	`- git remote rm origin`
	`- git remote add origin git@github.com:USERNAME/REPO.git`
	`- git fetch origin master`
	`- git branch master FETCH_HEAD`
	`install:`
	`- pip install -U --upgrade-strategy=eager 'Nikola[extras]'`
	`script:`
	`- nikola build && nikola github_deploy -m 'Nikola auto deploy [ci skip]'`
	`notifications:`
	`email:`
	`on_success: change`
	`on_failure: always`

Next, we need to generate a SSH key for Travis CI.

echo id_rsa >> .gitignore
echo id_rsa.pub >> .gitignore
ssh-keygen -C TravisCI -f id_rsa -N ''

Open the id_rsa.pub file and copy its contents. Go to GitHub → your page repository → Settings → Deploy keys and add it there. Make sure Allow write access is checked.

And now, time for our venture into the Ruby world. Install the travis gem:

gem install --user-install travis

You can then use the travis command if you have configured your $PATH for RubyGems; if you haven’t, the tool will output a path to use on the first lines (eg. ~/.gem/ruby/2.0.0/bin/travis)

We’ll use the Travis CI command-line client to log in (using your GitHub password), enable the repository and encrypt our SSH key. Run the following three commands, one at a time (they are interactive):

travis login
travis enable
travis encrypt-file id_rsa --add

Commit everything to GitHub:

git add .
git commit -am "Automate builds with Travis CI"

Hopefully, Travis CI will build your site and deploy. Check the Travis CI website or your e-mail for a notification. If there are any errors, make sure you followed this guide to the letter.

(Revision 4a, 2020-04-24: Add link to GitHub Actions version of this guide)