Using the BigWigs Packager with GitHub Actions

If you maintain multiple addons on CurseForge, WowInterface and Wago while also embedding any libraries it can be bothersome 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:
* 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 any external libraries, for example 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
===Local and external embeds===
Listing external embeds is convenient for packaging the latest version of a library instead of hardcoding it.
When the libaries are packaged externally, you naturally would still want to have your own local Ace3 libs in your working copy without checking them out to the repository:
* Use e.g. Ace3 standalone by dropping the Ace3 in the AddOns folder and specifying ## OptionalDeps: Ace3 in your TOC. A library can be used standalone if it has a TOC file.
* Or put the Ace3 libs in the Libs folder and exclude it from the repository with .gitignore
==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: 
 ## Version: @project-version@
 ## Title: MyAddOn
 ## Notes: Does something neat
 ## Author: Your Name
 ## 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. You can reference the detailed GitHub Actions workflow example on the BigWigs wiki or use the below one.
.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
 # this must be explicitly configured with read-write permissions on the repository
 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@v3
 with:
 fetch-depth: 0 # reads history for commit changelog
 - uses: BigWigsMods/packager@v2
===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
==Creating a release==
Make sure your workflow and TOC file with project IDs are committed and pushed. (Note that if you push an initial 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!
==Multiple client flavors==
: Reference: Building for multiple game versions, GitHub Actions workflow
* Addons can check the current game flavor with the WOW_PROJECT_ID constant.
* The packager can automatically generate multiple TOC files, for example this will create one zip file with three different TOCs: AddonName.toc, AddonName_Wrath.toc, AddonName_Vanilla.toc
AddonName.toc
 ## Interface: 
 ## Interface-Wrath: 
 ## Interface-Classic: 
jobs:
 release:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 with:
 fetch-depth: 0
 - uses: BigWigsMods/packager@v2
 # automatically generates game type specific TOC files
 with:
 args: -S
==Troubleshooting==
===Why am I getting "resource not accessible by integration" errors in my workflow?===
As of February 2023 the default permissions granted to the automatically generated GITHUB_TOKEN for new repositories were changed to only allow read-only accesshttps://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/. You will need to modify the permissions of the token and grant it write access to allow the packager to publish releases to your repository.
==See also==
* Kemayo: World of Warcraft addon packaging but with GitHub Actions this time
* WowInterface: Guide: Automagically package and publish addons (TravisCI)
* Example reference addon: https://github.com/ketho-wow/HideTutorial
* Symlinking AddOn folders
==References==