Skip to content

Automate the upstream pin bump, derive the task table from source #126

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gantoine merged 2 commits into from
Aug 31, 2026
Merged

Automate the upstream pin bump, derive the task table from source #126

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
065d609
chore: derive the scheduled-task table from upstream, and automate th…
gantoine Aug 31, 2026
ace115c
run fmt
gantoine Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 160 additions & 0 deletions .github/workflows/romm-release-bump.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
name: Bump pinned romm ref

# The generated reference pages (env vars, scheduled tasks, supported platforms)
# are built from rommapp/romm at the ref pinned in scripts/sources.toml. Nothing
# was moving that pin, so it sat on 5.1.0-beta.2 while upstream shipped 5.2.0 and
# every variable added in between went undocumented (#124).
#
# This polls for new upstream releases and opens a PR with the regenerated
# snippets. rommapp/romm can also trigger it directly by sending a
# `romm-release` repository_dispatch on publish.

on:
schedule:
# Daily at 06:00 UTC. Upstream releases are infrequent, so this is
# really a safety net.
- cron: 0 6 * * *
workflow_dispatch:
inputs:
# trunk-ignore(checkov/CKV_GHA_7)
ref:
description: Ref to pin (defaults to romm's latest stable release)
required: false
type: string
repository_dispatch:
types: [romm-release]

concurrency:
group: romm-release-bump
cancel-in-progress: false

permissions:
contents: write # Push the bump branch
pull-requests: write # Open the bump PR

jobs:
bump:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Checkout repo
uses: actions/checkout@v4.3.0

- name: Resolve target ref
id: target
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
INPUT_REF: ${{ github.event.inputs.ref }}
DISPATCH_REF: ${{ github.event.client_payload.ref }}
run: |
set -euo pipefail
target="${INPUT_REF:-${DISPATCH_REF:-}}"
if [ -z "$target" ]; then
target=$(gh release view --repo rommapp/romm --json tagName --jq .tagName)
fi
current=$(grep -E '^ref = ' scripts/sources.toml | sed -E 's/.*"(.*)".*/\1/')
echo "target=$target" >> "$GITHUB_OUTPUT"
echo "current=$current" >> "$GITHUB_OUTPUT"
if [ "$target" = "$current" ]; then
echo "changed=false" >> "$GITHUB_OUTPUT"
echo "Already pinned to $current, nothing to do."
else
echo "changed=true" >> "$GITHUB_OUTPUT"
echo "Bumping $current -> $target"
fi

- name: Install uv
if: steps.target.outputs.changed == 'true'
uses: astral-sh/setup-uv@v6.7.0
with:
enable-cache: true
cache-dependency-glob: uv.lock

- name: Set up Python
if: steps.target.outputs.changed == 'true'
uses: actions/setup-python@v6.0.0
with:
python-version-file: .python-version

- name: Install dependencies
if: steps.target.outputs.changed == 'true'
run: uv sync --all-extras --dev

- name: Update pinned ref
if: steps.target.outputs.changed == 'true'
env:
TARGET: ${{ steps.target.outputs.target }}
run: |
set -euo pipefail
sed -i -E "s|^ref = \".*\"$|ref = \"$TARGET\"|" scripts/sources.toml
grep -E '^ref = ' scripts/sources.toml

- name: Regenerate snippets
if: steps.target.outputs.changed == 'true'
run: |
uv run python -m scripts.gen_env_vars
uv run python -m scripts.gen_scheduled_tasks
uv run python -m scripts.gen_platforms

# Match the prettier version trunk pins in .trunk/trunk.yaml, so the
# bump PR doesn't fail its own trunk-check.
- name: Format generated snippets
if: steps.target.outputs.changed == 'true'
run: npx --yes prettier@3.5.2 --write 'docs/resources/snippets/*.md'

# The bump PR is opened with GITHUB_TOKEN, which does not trigger
# other workflows, so pr-checks won't run on it. Build here instead
# so a bump that breaks the docs never reaches review looking green.
- name: Build docs (strict)
if: steps.target.outputs.changed == 'true'
run: uv run mkdocs build --strict

- name: Open bump PR
if: steps.target.outputs.changed == 'true'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TARGET: ${{ steps.target.outputs.target }}
CURRENT: ${{ steps.target.outputs.current }}
run: |
set -euo pipefail
branch="chore/bump-romm-ref-$TARGET"

if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
echo "Branch $branch already exists, so this bump is already open."
exit 0
fi

git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git checkout -b "$branch"

paths="scripts/sources.toml docs/resources/snippets"
if git diff --quiet -- $paths; then
echo "Ref moved but no generated output changed, nothing to open."
exit 0
fi

git add $paths
git commit -m "chore: bump pinned romm ref to $TARGET"
git push origin "$branch"

{
echo "Bumps \`scripts/sources.toml\` from \`$CURRENT\` to"
echo "[\`$TARGET\`](https://github.com/rommapp/romm/releases/tag/$TARGET)"
echo "and regenerates the reference snippets."
echo
echo "The diff is upstream drift, not hand-written prose. Skim it for"
echo "anything that reads wrong, then merge."
echo
echo "\`mkdocs build --strict\` passed in the job that opened this PR."
echo "PRs opened with \`GITHUB_TOKEN\` do not trigger \`pr-checks\`, which"
echo "is why the build runs inline."
echo
echo "Opened automatically by \`.github/workflows/romm-release-bump.yml\`."
} > /tmp/pr-body.md

gh pr create \
--base main \
--head "$branch" \
--title "chore: bump pinned romm ref to $TARGET" \
--body-file /tmp/pr-body.md
2 changes: 0 additions & 2 deletions docs/install/zimaos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,6 @@ The defaults work out of the box, so everything below is optional.

To change container settings, use the options button in the upper-right corner of the app tile. ZimaOS offers both a form-based editor and a YAML editor for the underlying compose file, so you can set volumes, ports, and env vars either way.

![The options button on the RomM app tile](../resources/zimaos/app-tile-options.png)

![Editing RomM's volumes and environment variables](../resources/zimaos/edit-config.png)

The env vars are the same ones documented in [Quick Start](../getting-started/quick-start.md) and the [Environment Variables reference](../reference/environment-variables.md). Two worth setting early:
Expand Down
34 changes: 17 additions & 17 deletions docs/resources/snippets/scheduled-tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
<!-- AUTOGENERATED by scripts/gen_scheduled_tasks.py: do not edit. -->

| Task | Type | Default schedule | Enable var | Schedule/delay var | Purpose |
| ------------------------------- | --------- | ---------------- | -------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| Scheduled rescan | Scheduled | `0 3 * * *` | `ENABLE_SCHEDULED_RESCAN` | `SCHEDULED_RESCAN_CRON` | Rescan the entire ROM library for new or changed files. |
| Switch TitleDB update | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB` | `SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON` | Update the Nintendo Switch TitleDB index used for matching. |
| LaunchBox metadata update | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA` | `SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON` | Refresh the LaunchBox metadata store. |
| Convert images to WebP | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP` | `SCHEDULED_CONVERT_IMAGES_TO_WEBP_CRON` | Convert existing PNG, JPG, BMP, TIFF and GIF media to WebP. |
| Cleanup orphaned resources | Scheduled | `0 5 * * *` | `ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCES` | `SCHEDULED_CLEANUP_ORPHANED_RESOURCES_CRON` | Delete covers, screenshots and other resources left behind by deleted ROMs. |
| RetroAchievements progress sync | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC` | `SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRON` | Update RetroAchievements progress for all users. |
| Push-pull device sync | Scheduled | `*/30 * * * *` | `ENABLE_SYNC_PUSH_PULL` | `SYNC_PUSH_PULL_CRON` | Sync saves with registered devices over SSH/SFTP. |
| Netplay cleanup | Scheduled | `*/30 * * * *` | `-` | `-` | Clean up empty netplay rooms. Always on, not configurable. |
| Upload tmp cleanup | Scheduled | `0 * * * *` | `-` | `-` | Remove orphaned chunked-upload temp directories. Always on, not configurable. |
| ZIP cache cleanup | Scheduled | `0 4 * * *` | `-` | `-` | Remove stale cached ZIP files on a tiered TTL. Always on, not configurable. |
| Cleanup missing ROMs | Manual | `-` | `-` | `-` | Delete database entries for ROMs flagged as missing from the filesystem. |
| Recompute save content hashes | Manual | `-` | `-` | `-` | Recompute content hashes for stored saves. |
| Sync folder scan | Manual | `-` | `-` | `-` | Scan device sync folders for new save files. |
| Filesystem watcher | Watcher | `-` | `ENABLE_RESCAN_ON_FILESYSTEM_CHANGE` | `RESCAN_ON_FILESYSTEM_CHANGE_DELAY` | Watch the library folder and trigger a rescan on changes. |
| Sync folder watcher | Watcher | `-` | `ENABLE_SYNC_FOLDER_WATCHER` | `SYNC_FOLDER_SCAN_DELAY` | Watch the sync folder and trigger a scan on changes. |
| Task | Type | Default schedule | Enable var | Schedule/delay var | Purpose |
| ----------------------------------------- | --------- | ---------------- | -------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scheduled netplay cleanup | Scheduled | `*/30 * * * *` | `-` | `-` | Cleans up empty netplay rooms. Always on, not configurable. |
| Scheduled ZIP cache cleanup | Scheduled | `0 4 * * *` | `-` | `-` | Removes stale cached ZIP files based on tiered TTL. Always on, not configurable. |
| Scheduled upload tmp cleanup | Scheduled | `0 * * * *` | `-` | `-` | Cleans up orphaned chunked-upload temp directories. Always on, not configurable. |
| Cleanup orphaned resources | Scheduled | `0 5 * * *` | `ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCES` | `SCHEDULED_CLEANUP_ORPHANED_RESOURCES_CRON` | Clean up orphaned resources in the ROMs directory. |
| Scheduled rescan | Scheduled | `0 3 * * *` | `ENABLE_SCHEDULED_RESCAN` | `SCHEDULED_RESCAN_CRON` | Rescans the entire library. |
| Scheduled Switch TitleDB update | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB` | `SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON` | Updates the Nintendo Switch TitleDB file. |
| Scheduled LaunchBox metadata update | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA` | `SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON` | Updates the LaunchBox metadata store. |
| Convert images to WebP | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP` | `SCHEDULED_CONVERT_IMAGES_TO_WEBP_CRON` | Convert existing image files (PNG, JPG, BMP, TIFF, GIF) to WebP format for better performance. |
| Scheduled RetroAchievements progress sync | Scheduled | `0 4 * * *` | `ENABLE_SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC` | `SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRON` | Updates RetroAchievements progress for all users. |
| Push-Pull Sync | Scheduled | `*/30 * * * *` | `ENABLE_SYNC_PUSH_PULL` | `SYNC_PUSH_PULL_CRON` | Sync saves with devices via SSH/SFTP. |
| Cleanup missing ROMs | Manual | `-` | `-` | `-` | Delete all ROMs flagged as missing from the filesystem from the database. |
| Recompute save content hashes | Manual | `-` | `-` | `-` | Re-scan every save row and rewrite content_hash with the current compute_content_hash algorithm. One-time recovery after the zip-hash dispatch fix. |
| Sync Folder Scan | Manual | `-` | `ENABLE_SYNC_FOLDER_WATCHER` | `-` | Scan device sync folders for new save files. |
| Filesystem watcher | Watcher | `-` | `ENABLE_RESCAN_ON_FILESYSTEM_CHANGE` | `RESCAN_ON_FILESYSTEM_CHANGE_DELAY` | Watch the library folder and trigger a rescan on changes. |
| Sync folder watcher | Watcher | `-` | `ENABLE_SYNC_FOLDER_WATCHER` | `SYNC_FOLDER_SCAN_DELAY` | Watch the sync folder and trigger a scan on changes. |
Binary file removed docs/resources/zimaos/app-tile-options.png
View file
Open in desktop
Binary file not shown.
Binary file modified docs/resources/zimaos/appstore.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/resources/zimaos/edit-config.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading