New Build With Muddler GitHub Action

As part of my efforts to make Muddler easier to adopt and my general preference for automation in my own project I have created a GitHub action for building your project with Muddler. The action is on the GitHub action market HERE

What’s a GitHub action and why should I care?

GitHub actions are GitHub’s mechanism to build and/or publish your project. This is useful when you are working with others on a project especially, as GitHub can build your project and make the outcome available for testing without the other people working on it having to download and build it themselves.

Enough with the theory, old man. Concrete examples!

As part of developing the action to build a project with Muddler I set up my LusterniaChatTabs project to use it, even though I’m the only one working on it. Checking an action file into the .github/workflows directory of your project will cause it to be run by GitHub at the appropriate times, as defined by the file. In this case, the file is .github/workflows/ci.yml .

Configuration

Here’s what it looks like, with comments added for explanation.

# The name of the action, it is used for display in the actions view in GitHub
name: CI

# This section controls when the action runs. In this case, when code is checked
# into the main branch or when a pull request is made targeting the main branch.
# If your projects default branch is something else, such as 'development'
# then you would use that instead of main below
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# Including this lets your run the action on demand as well
  workflow_dispatch:

# The jobs (collection of steps) for the action
jobs:
  # This collection is called 'build'
  build:
    # build on GitHub's latest ubuntu image
    runs-on: ubuntu-latest

    # The steps to follow for the 'build' job
    steps:
      # this step checks out the project repository to work on
      - uses: actions/checkout@v2

      # this is the step I made, which builds your project with Muddler
      # it will show up as "Muddle" in the GitHub web interface later
      - name: Muddle
        uses: demonnic/build-with-muddler@v1.2
      
      # This step uploads the artifact for you and others to download
      - name: Upload Artifact
        uses: actions/upload-artifact@v2
        with:
          # build/tmp/ is the directory muddler makes the mpackage out of
          # GitHub only allows you to upload zip files, so we let them
          # zip it up and upload it. That's all the .mpackage is anyway
          # just with a different file extension
          name: LusterniaChatTabs
          path: build/tmp/

In use

I will not go into detail on how to create a PR (Pull Request) in this post, there are a wealth of resources online which can show you how to do this, but if enough people ask for it I’ll make a post focusing on that. But I will show the workflow in action, via the artistic medium of captioned screenshots.

By clicking on the ‘Details’ link (shown by the red arrow above) you bring up information on the workflow run.

You can get further information on the Muddle step (so named in the ci.yml file above) by clicking the expansion arrow marked by the red arrow.

The build-with-muddler step determines the latest release of muddler and downloads it to use, unless you specify a version, and then runs it to assemble your package for you. Thanks to the “Upload Artifact” step we defined, the artifact is available to download and install in Mudlet for testing.

Click the Artifacts expander and you can click on the artifact name (LusterniaChatTabs in this case) and it will download the zip file. This can be installed into Mudlet using Mudlet’s package manager.

If the action runs successfully, then it will clear the check for the Pull Request, and if not then the check fails and needs to be fixed before the PR is merged.

And that’s it in a nut shell. I will make a post on setting up your Mudlet project for Muddler soon, but I was too excited about making it a GitHub action which I and others could use for automation and wanted to get this post put together to help get the word out.