Forge Updater

Uploads new builds to FantasyGrounds Forge and updates item page descriptions without requiring user input. It is intended for use in CI release workflows such as one I use here.

Warning

Markdown parsing is not quite as permissive as GitHub. If you use tables, you must have an empty line directly before them.

Warning

FG Forge does not allow inline images. To work around this, images are replaced by links using the image's alt text. To ensure this can work, be sure to configure alt text on your README images and reference them via URL (not relative file paths).

Getting Started / Before Using

To run this code, you'll need to have Python 3.11+ installed on your machine. You'll also need to install the required packages by running the following commands from inside the project folder:

pip install -U pip uv

uv venv

source .venv/bin/activate # Linux or macOS
.venv\Scripts\activate # Windows

uv pip install .

Usage

1. Put the ext file to upload into the project folder.

2. [OPTIONAL] Create a .env file in the project folder containing the following (but with your information):

Note

You can add these values directly to your environment variables. If no environment variables are set and no .env file is found, command line will prompt for Forge login credentials and item ID. Build will be uploaded and added to LIVE. Description will not be updated.

# your FG forum username
FG_USER_NAME=**********
# your FG forum password
FG_USER_PASS=**********
# the item ID of the FG Forge item you want to modify
FG_ITEM_ID=33
# file(s) (supported types -- ext, pak, mod, etc) you want to upload (relative to project folder or absolute paths; comma-separated list or path to directory if multiple)
FG_UL_FILE=path/to/file.ext

# [OPTIONAL] set this to FALSE to skip build uploading
FG_UPLOAD_BUILD=TRUE
# [OPTIONAL] set this to "TEST" or "NONE" if you would rather target those channels
FG_RELEASE_CHANNEL=LIVE

# [OPTIONAL] set this to TRUE to prevent replacing the description with the contents of README.md
FG_README_UPDATE=FALSE
# [OPTIONAL] set this to TRUE to remove images instead of creating links
FG_README_NO_IMAGES=FALSE

3. Run one of the following commands from inside the project folder:

fg-forge-uploader

python -m src.main