How To Validate Katacoda Scenarios with GitHub Actions

#github

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 }}

Top comments (8)

Bill Wang • May 16 '20 • Edited

To save everyone's time, here is the whole .github/workflows/actions.yml file

name: Validate Katacoda
on: push
jobs:
  build:
    name: Validate
    runs-on: ubuntu-latest
    steps:
    - id: checkout-code
      name: Checkout code
      uses: actions/checkout@v2
    - id: install-katacoda-cli
      name: Install Katacoda CLI
      run: |
        sudo npm i katacoda-cli --global
    - id: validate
      name: Validate Katacoda scenarios
      run: |
        katacoda validate:all --repo ${{ github.workspace }}
    - id: validate-markdown
      name: Validate Katacoda Markdown
      run: |
        sudo gem install mdl
        mdl ${{ github.workspace }}

Sualeh Fatehi • May 19 '20

Thanks for posting this. I should have mentioned that the step to install the Katacoda cli and to run the validation can be combined into a single step. They are kept separate for purposes of illustration in the article.

Krzysztof Pudłowski • Sep 25 '20

Nice tutorial.
But using it I have a lot of warnings

1.

Run sudo npm i katacoda-cli --global
npm WARN deprecated @hapi/joi@15.1.1: joi is leaving the @hapi organization and moving back to 'joi' (github.com/sideway/joi/issues/2411)
npm WARN deprecated request@2.88.2: request has been deprecated, see github.com/request/request/issues/...
npm WARN deprecated request-promise@4.2.6: request-promise has been deprecated because it extends the now deprecated request package, see github.com/request/request/issues/...
npm WARN deprecated @hapi/bourne@1.3.2: This version has been deprecated and is no longer supported or maintained
npm WARN deprecated @hapi/hoek@8.5.1: This version has been deprecated and is no longer supported or maintained
npm WARN deprecated @hapi/address@2.1.4: This version has been deprecated and is no longer supported or maintained
npm WARN deprecated @hapi/topo@3.1.6: This version has been deprecated and is no longer supported or maintained
npm WARN deprecated urix@0.1.0: Please see github.com/lydell/urix#deprecated
npm WARN deprecated resolve-url@0.2.1: github.com/lydell/resolve-url#depr...
npm WARN deprecated har-validator@5.1.5: this library is no longer supported
/usr/local/bin/katacoda -> /usr/local/lib/node_modules/katacoda-cli/bin/run