Automate Blender Add-on Creation on GitHub

If you’re new to developing add-ons for Blender, there are two ways that it supports their installation from its Preferences UI:

  1. Single-file add-ons with a unique name such as my_blender_addon.py or zipped as my_blender_addon.zip (with no subdirectories in the zip file).
  2. Directory-style add-ons stored in a zip with a root directory (the name of the add-on package) which contains an __init.py__ file and zero or more sub-modules. See regular Python packages for more information.

For a simple, single-file add-on it’s possible to share a link to the latest version of the file shown on your project’s GitHub repository. However, if your add-on contains multiple-files or you wish to keep a version history, it gets a little more difficult.

While you could simply direct users to get your add-on from the Download Zip link that GitHub provides, this will always be the latest commit, and it will contain all files in the repository including any test scenes or other files such as .gitignore that do not need to be included. The downloadable zip file and the root directory inside it (the Python package) will also have the name of the main branch appended. This could cause issues if you manually create a zip file at some point without the branch name included as it would result in two copies of your add-on being found by Blender.

GitHub Actions and Workflows

Luckily, the process of creating a proper zip file for a new version release can be automated using a custom GitHub Action Workflow. A GitHub workflow is just a YAML text file that is created in your Git repository under the .github/workflows directory. It uses GitHub’s workflow syntax to run commands based on certain repository events (such as when new commits are pushed). These commands run in a custom environment (usually Linux) on GitHub’s servers and can interact with files stored in the repository and create new assets that can be included in a release. Once created, a workflow’s execution can be monitored from the GitHub project’s Action tab to verify its success or view errors.

The documentation for GitHub Actions and Workflows is pretty extensive, so I advise browsing through it to see what is possible. For the most part, you have available all the basic tools found in an Ubuntu Linux installation as well as the GitHub Command Line Interface gh tool that can be used to perform many GitHub-specific actions such as creating new releases or creating and altering issues.

A GitHub Workflow to Automate Release Creation

Below is the entire GitHub workflow file that I use to build new releases whenever I tag a commit with a semantic version number (ex: v1.2.3 or v1.4):

BuildRelease.yml
# Build a release containing .zip of the (filtered) contents of the repository
# when a new tag is pushed with a semantic versioning format.
name: Build Release

on:
  push:
    tags: ["v[0-9]+.[0-9]+.[0-9]+"]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # Checkout the repository under a subdirectory (repository-name/) to
      # make zipping easier. Note: 'gh' or 'git' commands must be executed
      # *after* changing into the repository's directory.
      - uses: actions/checkout@v3
        with:
          path: ${{ github.event.repository.name }}

      # Create a filtered zip of the repository.
      - name: Zip Repository (excludes .git*)
        run: |
          zip -r ${{ github.event.repository.name }}.zip \
            ${{ github.event.repository.name }} \
            -x "${{ github.event.repository.name }}/.git*"          
      
      # Create a new GitHub release using the tag name or commit id.
      - name: Create versioned build with filtered zip file.
        run: |
          cd ${{ github.event.repository.name }}
          gh release create ${{github.ref_name}} --generate-notes \
            ../${{ github.event.repository.name }}.zip          
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The workflow listens for a Git tag push event on GitHub whose name matches the specified regular expression for semantic versioning. It then starts a job, running on Ubuntu Linux, that first checks out the repository’s files into a subdirectory (to match the layout required for Blender add-ons). It then creates a <repository_name>.zip file that excludes any files starting with .git (i.e. .git/, .gitignore, and .gitlab/). Once that completes, it changes into the repository’s directory and issues the gh release command. This command creates a new GitHub release with automated release notes. If you keep your own release notes, you can include them as well by adding the -F <notes file> parameter.

To use this workflow, simply create the .github/workflows/ directory in your repository and save the above BuildRelease.yml there. Then commit and push the changes to GitHub. You should now see a Build Release entry on the Actions tab on your GitHub repository. This will show a log of each time the workflow was executed and if it succeed or failed. Any errors can be viewed by clicking on the log entry. If you wish to make changes to the workflow, I found it easiest to click the Build Release workflow entry on the left side and then the BuildReleases.yml link at the top of the log and edit it directly on GitHub.

Create a New Add-on Release on GitHub

When it’s time to create a new release for your add-on:

  • Commit new changes (git commit) and push them to GitHub (git push origin) as you normally would.
  • Next, create a tag for the new version: git tag v1.0.3
    • To view a list of previously created tags: git tag
  • Finally, push the new tag to GitHub: git push origin v1.0.3

GitHub should now execute the workflow and create a new v1.0.3 “Release” which is shown on the project’s main page (or the right side or bottom). The release will contain an asset for the zip file that was created by the workflow.

To create a link which always points to the latest release:

  • Append: /releases/latest/download/my_blender_addon.zip to your GitHub project’s main URL.

Deleting a Tag and Release

If you happen to create a release a little too quickly, you can remove the tag in Git and delete the tag and release on GitHub:

  • To delete the local tag: git tag -d v1.0.3
  • To delete the tag on GitHub: git push --delete origin v1.0.3
  • To delete the release on GitHub, click on the Releases link on the project’s main page. Then click on the trash can icon for the desired release.

You should now be able to follow the steps above to recreate the same version release.

Reusing a Workflow in Multiple Repositories

If you end up creating several different repositories and wish to use the same workflow in each, GitHub does provide a way to reuse workflows. There are a couple of small limitations – the worst being that the re-used workflow must be in a public repository. I have not yet setup my projects to use a reusable workflow, but once I do, I’ll update this section and describe the process.