Using the BigWigs Packager with GitHub Actions
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.
Contents
BigWigs packager
The BigWigs packager has a couple of advantages over the CurseForge packager and supports:
- Uploading to CurseForge, WowInterface and GitHub (as a release).
- Packaging for multiple game versions: Classic and Retail.
- Using GitHub Actions to automate your workflow.
The documentation is available on the project page:
- Preparing the PackageMeta File
- Repository Keyword Substitutions
- Localization Substitution
- GitHub Actions workflow
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
and -w wowi-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 @project-version@
substitution keyword is the tag name if on a tag, otherwise the short revision.
MyAddOn.toc
## Interface: 90005 ## Version: @project-version@ ## Title: MyAddOn ## Notes: Does something neat ## Author: YourName ## X-Curse-Project-ID: 123456 ## X-WoWI-ID: 12345 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 }}
# 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 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-tokensWOWI_API_TOKEN
https://www.wowinterface.com/downloads/filecpl.php?action=apitokens
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!
Symlinks
Instead of doing git init
in your addon folder consider symlinking your addon repository folders. (Windows: New-Item for PowerShell or mklink for cmd)
New-Item -ItemType SymbolicLink -Path "D:\Game\World of Warcraft\_retail_\Interface\AddOns\HelloWorld" -Value "D:\Repo\HelloWorld"
Makes the PTR and Beta clients use the same AddOns folder as Retail.
- You might have to delete the Path folder first. You can also append
-Force
to the command if the Path folder already exists but is an empty folder.
New-Item -ItemType SymbolicLink -Path "D:\Game\World of Warcraft\_ptr_\Interface\AddOns" -Value "D:\Game\World of Warcraft\_retail_\Interface\AddOns" New-Item -ItemType SymbolicLink -Path "D:\Game\World of Warcraft\_beta_\Interface\AddOns" -Value "D:\Game\World of Warcraft\_retail_\Interface\AddOns"
- If your addon soft embeds libraries with .pkgmeta, you can use those libraries as standalone addons by e.g. putting the Ace3 folder in your AddOns folder and making sure it's listed in the TOC
## OptionalDeps: Ace3
- If your addon consists of multiple folders by using move-folders you can create symlinks to the subfolders, for example:
New-Item -ItemType SymbolicLink -Path "D:\Game\World of Warcraft\_retail_\Interface\AddOns\WardrobeSort" -Value "D:\Repo\WardrobeSort" New-Item -ItemType SymbolicLink -Path "D:\Game\World of Warcraft\_retail_\Interface\AddOns\WardrobeSortData" -Value "D:\Repo\WardrobeSort\Data"