GitHub Integration Notes

[shawnb61]

Some notes on the new GitHub integration offered by the customization site.

GitHub Integration
There is one difference between a GitHub mod/theme and one hosted by SMF: the location of the mod/theme packages themselves.  When using the GitHub integration on our Customization Site, mods and themes go thru the exact same review & approval process as regular mods and themes.  They have all the same requirements.  The difference is that when you click on a link to download a package, it is downloaded directly from GitHub rather than from the SMF Customization Site.

Requirements
- You must create and tag a release on your repo.  When creating the release, you must attach your mod or theme as a binary asset to the release.
- The GitHub repo must be public.
- There is only one mod or theme per repo.
- When specifying the repo, specify the url to the repo... (I.e., not the url to the mod or theme...)
- When specifying the repo, no trailing slashes.
- All normal mod/theme rules apply: xml file required, license required, package id must be unique, etc.

Images may be specified & will be stored locally within SMF as usual.  It is only the packages that are stored at and retrieved from GitHub.

(Note that GitHub has a "package" offering that has a completely different meaning...  We are just attaching our mods/themes to GitHub releases for download; we are not creating "GitHub packages"...)

Converting an Existing Mod to GitHub
If you edit an existing mod or theme, you will see a function to "Convert to a GitHub Repo".  This will change the source of your packages from the SMF site to GitHub, and further will delete all of the packages from SMF. There is no halfway point: you are downloading the packages either from SMF or from GitHub.

This applies to all versions of your mod or theme, so be careful.  If you have 10 historical versions on SMF, and you added the latest one to GitHub, and convert to GitHub, there will only be one version available going forward - the one on GitHub.  So before converting an existing mod or theme to GitHub, ensure all versions you wish to keep are up on GitHub.

Pulling New Packages from GitHub Upon Edit
If you have a GitHub mod or theme, new packages are pulled from GitHub every time you edit and save the mod or theme on the Customization Site.  The latest eight releases are examined, and already processed ones are ignored.  Any invalid package (such as those without a license file) will be ignored.

Fetching New Packages from GitHub via Webhooks
Using GitHub Webhooks, you can have updated packages pushed from GitHub to the Customization Site when you publish or edit a release on GitHub.  You must add a GitHub Webhook to your repo.  The proper parameters for the GitHub Webhook creation may be found under the "Auto Update" link visible when you edit your mod on the Customization Site.  When a release is made on a repo with a valid package attached as an asset, the webhook will notify this site of the event and qualifying assets will then be made visible here. The latest eight releases are examined, and already processed ones are ignored.  Any invalid package (such as those without a license file) will be ignored.

I hope this helps!  We may modify this post over time as the functionality evolves.

Edits:
 - 5/11/22 - Removed limitations section.  Issues listed (reset download counter, inability to edit images) have been addressed.

[shawnb61]

Note that the limitations initially listed above have been addressed.