Using the BigWigs Packager with GitHub Actions

Category nav.

If you maintain multiple addons on CurseForge and WowInterface and also embed any libraries it can take a lot of time just to update them.

BigWigs packager

The BigWigs packager has a couple of advantages over the CurseForge packager and supports:

Uploading to CurseForge, WowInterface, Wago, and GitHub (as a release).
Packaging for multiple game versions.
Using GitHub Actions to automate your workflow.

The documentation is available on the project page:

Getting started

For this tutorial you will need:

To be familiar with Git, guides like try.github.io and git - the simple guide will help you on your way.
To install the Git client or one of the available GUI clients. VS Code has integrated Git support.
A GitHub repository.

The basic idea is: create a local Git repository -> make some changes -> stage your changes -> commit them locally -> push the commits to a remote repository.

PackageMeta file

The PackageMeta file configures the packager. It's mostly used for embedding external libraries so if you have a simple addon, chances are you don't need it.

For example when embedding most of the Ace3 framework:

.pkgmeta

package-as: MyAddOn

externals:
  Libs/LibStub: https://repos.wowace.com/wow/libstub/trunk
  Libs/CallbackHandler-1.0: https://repos.wowace.com/wow/callbackhandler/trunk/CallbackHandler-1.0
  Libs/AceAddon-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceAddon-3.0
  Libs/AceComm-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceComm-3.0
  Libs/AceConfig-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceConfig-3.0
  Libs/AceConsole-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceConsole-3.0
  Libs/AceDB-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceDB-3.0
  Libs/AceDBOptions-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceDBOptions-3.0
  Libs/AceEvent-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceEvent-3.0
  Libs/AceGUI-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceGUI-3.0
  Libs/AceHook-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceHook-3.0
  Libs/AceLocale-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceLocale-3.0
  Libs/AceSerializer-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceSerializer-3.0
  Libs/AceTimer-3.0: https://repos.curseforge.com/wow/ace3/trunk/AceTimer-3.0

TOC file

The project IDs should be listed in the TOC file (or alternatively as -p curse-id, -w wowi-id, and -a wago-id arguments in the workflow).

The Curse ID is listed on the project page, e.g. 399282 on https://www.curseforge.com/wow/addons/hidetutorial
The WoWInterface ID is in the URL, e.g. 25635 in https://www.wowinterface.com/downloads/info25635-HideTutorial.html
The Wago project ID is listed on the developer dashboard.

The @project-version@ substitution keyword is the tag name if on a tag, otherwise the short revision.

MyAddOn.toc

## Interface: 90100
## Version: @project-version@
## Title: MyAddOn
## Notes: Does something neat
## Author: YourName
## X-Curse-Project-ID: 123456
## X-WoWI-ID: 12345
## X-Wago-ID: abcdef12

MyAddOn.lua

GitHub workflow

A workflow is a configurable automated process made up of one or more jobs. There is a detailed GitHub Actions workflow example on the BigWigs wiki.

You can also copypaste the below workflow or reference the WowAce Community example workflow.

.github/workflows/release.yml

name: Release AddOn # description of this workflow, can be anything you want

# triggers when pushing a tag
on:
  push:
    tags:
      - '**'

env:
  CF_API_KEY: ${{ secrets.CF_API_KEY }}
  WOWI_API_TOKEN: ${{ secrets.WOWI_API_TOKEN }}
  WAGO_API_TOKEN: ${{ secrets.WAGO_API_TOKEN }}
  # for github releases, this secret is automatically provided to the workflow
  GITHUB_OAUTH: ${{ secrets.GITHUB_TOKEN }}

jobs:
  release: # "release" is a job, you can name it anything you want
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1

      - uses: BigWigsMods/packager@master

Environment variables

The workflow accesses encrypted environment variables a.k.a. secrets, they can be created via Settings -> Secrets -> New repository secret

Generate the API tokens and assign them to your secrets:

CF_API_KEY https://wow.curseforge.com/account/api-tokens
WOWI_API_TOKEN https://www.wowinterface.com/downloads/filecpl.php?action=apitokens
WAGO_API_TOKEN https://addons.wago.io/account/apikeys

Tutorial BigWigs 1.png

Creating a release

Make sure your workflow and TOC file with project IDs are committed and pushed. (Note that if you push the new workflow at the same time with a tag, then the workflow will not trigger yet. Try pushing another tag.)

Now when pushing a new tag GitHub should automatically package a .zip file and upload to CurseForge, WoWInterface and GitHub releases!

Tutorial BigWigs 2.png