How To Validate Katacoda Scenarios with GitHub Actions

O’Reilly Katacoda is an online system that allows developers to develop technical teaching materials online very easily, using JavaScript and Markdown. Course content is run in Docker containers online, and gives a very real feel to learners. They can experiment in a shell from their web browser.

Katacoda projects are created on your development system, and pushed to a GitHub repository, where they are rendered by Katacoda by means of a webhook. This process does not allow you to test your changes locally before you publish, even though Katacoda has a rudimentary CLI. Since mistakes in course content can happen, it is a good idea to set up a GitHub Actions workflow to validate your project. It is quite simple to set this up.

First, read up on how to create a basic GitHub Actions workflow, and create one for your project. It will look something like this:

name: Validate Katacoda
on: push
jobs:
  build:
    name: Validate
    runs-on: ubuntu-latest
    steps:
    - id: checkout-code
      name: Checkout code
      uses: actions/checkout@v2

Next, install the Katacoda CLI in your GitHub Actions runner, by adding this step:

    - id: install-katacoda-cli
      name: Install Katacoda CLI
      run: |
        sudo npm i katacoda-cli --global

Now, you are ready to run the validation. Add the following step to your workflow:

    - id: validate
      name: Validate Katacoda scenarios
      run: |
        katacoda validate:all --repo ${{ github.workspace }}

That's all. Once you commit and push this workflow, it will run each time you make a change to your Katacoda course content, and validate your project.

However, if you want to go over and above for extra credits, you can use Markdown Lint to validate your Katacoda Markdown files.

Add the following step to your workflow:

    - id: validate-markdown
      name: Validate Katacoda Markdown
      run: |
        sudo gem install mdl
        mdl ${{ github.workspace }}