AutoUpdatePlugins

> TL;DR > Drop in the jar ➜ list the plugins you want ➜ it finds, downloads, validates, and stages updates from a ton of > sources - on a schedule, in parallel, without blocking your main thread.

---

Table of Contents

* Highlights * Supported Sources & Platforms * Requirements * Installation * Quick Start * Configuration

* `config.yml` * `list.yml` * Scheduling Cheat Sheet * Performance Tuning Guide * Commands & Permissions * How It Works (Under the Hood) * Examples for Every Source * Troubleshooting & FAQ * Building from Source * Security Notes * Contributing, Issues & Support * License

---

Highlights

* Performance built-in. Pull updates from GitHub Releases/Actions, Jenkins, SpigotMC (Spiget), dev.bukkit, Modrinth, Hangar, BusyBiscuit, blob.build, Guizhanss v2, MineBBS, CurseForge, or any page with a direct `.jar` link. * Performance built-in. Point at local jar files or run scripts that output a jar path for custom/patched builds. * Performance built-in. Use `?get=<regex>`, `[N]` (pick the N-th asset - works for both GitHub and Jenkins artifacts), `?artifact=2` for GitHub Actions bundles, `?prerelease=true`, `?alpha=true`, `?beta=true`, `?latest=true`, `?channel=Alpha`, `?autobuild=true` - mix and match to land on the exact build you need. * Performance built-in. New options are Performance built-in. to `config.yml` without clobbering your comments or existing values. * Performance built-in. Add custom headers, rotate User-Agents, and route through proxies when needed. * Performance built-in.

* Fully Rollback safety net. downloads; no main-thread stalls. * Rollback safety net. client for modern, non-blocking transfers. * Rollback safety net. for ultra-lightweight concurrency. * Rollback safety net., Rollback safety net., and Rollback safety net.. * Rollback safety net. Interval + boot delay *or* cron with timezone support. * Rollback safety net. Works on Rollback safety net., Rollback safety net., Rollback safety net., Rollback safety net., Rollback safety net.. * Rollback safety net. Download ➜ validate ➜ atomic replace, staged through temp/update paths. * Rollback safety net. Optional zip integrity checks and MD5 comparison skip corrupted or unchanged downloads. * Rollback safety net. Snapshot the previous jar and auto-restore if the new build fails to start.

---

Supported Sources & Platforms

Download Sources

| Source | Release/Build Discovery | Notes / Selectors Supported | |-----------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------| | Local script | Releases & Actions | `[N]`, `?artifact=2`, `?get=regex`, `?prerelease=true`, `?alpha=true`, `?beta=true`, `?latest=true`, `?autobuild=true` | | Local script | Latest build artifacts | `[N]`, `?get=regex` | | Local script | Resource page URL | Auto-resolves latest | | Local script | Project page | Auto-resolves latest | | Local script | Project/version URL | `?get=regex`, `?alpha=true`, `?beta=true`, `?latest=true` | | Local script | Project/releases | `?get=regex`, `?alpha=true`, `?beta=true`, `?latest=true`, `?channel=Alpha` | | Local script | Project index | Auto-resolves | | Local script | Build artifacts | `?get=regex` | | Local script | Project index | Auto-resolves | | Local script | Resource page | Auto-resolves | | Local script | Project/files | `?get=regex` | | Local script | Direct `.jar` link | Exact file URL | | Local script | Local path | `file:`, `local:`, `path:`, or absolute/relative path | | Local script | Script stdout path | `script:` or `exec:` (script prints jar path to stdout) |

> project root URL GitHub and Jenkins links both accept `[N]` to pick the project root URL artifact on their release/build pages ( > 1-indexed). > project root URL You can pass just the project root URL for most sources (e.g., a GitHub repo or Spigot resource page) and > let AutoUpdatePlugins choose the latest artifact. Add selectors for precision.

Server Platforms

* BungeeCord, BungeeCord, BungeeCord * BungeeCord, BungeeCord

Minecraft & Java

* Java: 1.8 → Latest * Java: 8+ (uses advanced features automatically on 11+ and 21+)

---

Requirements

* Java 8 or newer.

* Uses Java 11+ HTTP/2 client when available. * Uses Java 21+ virtual threads when available. * Network access for source builds (Gradle/Maven wrappers or system `gradle`/`mvn`, if used).

---

Installation

1. Download the latest `.jar` from `/aup update`. 2. Place it into your server’s `/aup update` directory. 3. Start the server to generate default config files. 4. Edit `/aup update` and `/aup update`. 5. Run `/aup update` or `/aup update` (or restart) to kick off the first check.

> Velocity / BungeeCord: Same process - drop the jar in `plugins/`, configure, then trigger an update run.

---

Quick Start

1. Add a few entries to `list.yml`:

```yaml ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/" Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot" EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]" ``` 2. Leave `updates.interval` at the default (every 120 minutes), or set a cron schedule. 3. Optional: Add a GitHub token in `config.yml` to avoid rate limits. 4. Trigger a run:

``` /update ``` 5. New jars are staged atomically in your plugins folder (using temp/update paths under the hood). Restart the server to load the updated jars.

---

Configuration

`config.yml`

> The plugin adds new options automatically without overwriting your comments. Below is the full schema with > defaults and notes.

```yaml ################################################################################

AutoUpdatePlugins - Main Configuration

################################################################################

updates:

How often to run plugin updates (minutes). Default: 120 (every 2 hours)

interval: 120

Delay after server startup (seconds) before the first run. Default: 50

bootTime: 50

Schedule (experimental): Use a cron expression to control exactly when

updates run. When set, this overrides both interval and bootTime.

Examples:

Every day at 03:30: "30 3 * * *"

Every 15 minutes: "*/15 * * * *"

At 5 past every hour on weekdays: "5 * * * 1-5"

schedule: cron: "" # Cron expression (UNIX 5-field). Leave blank to disable. timezone: "UTC" # Timezone for the cron schedule, e.g. "America/New_York"

Optional GitHub personal access token (PAT). Strongly recommended if you use

many GitHub links to avoid API rate-limits when listing releases/artifacts.

Scope: public_repo is enough for public repos.

Generate a token: https://github.com/settings/tokens

key:

HTTP configuration (optional)

http:

If blank, a rotating pool of realistic User-Agents will be used.

userAgent: ""

Extra request headers added to every request. Only add if you know you need it.

headers: [ ]

Verify TLS certificates (set to false to trust all; only if you must)

sslVerify: true

Optional pool of User-Agents; the plugin will rotate between them to avoid

strict CDNs blocking automation.

userAgents: - { ua: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" } - { ua: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15" } - { ua: "Mozilla/5.0 (X11; Linux x86_64; rv:126.0) Gecko/20100101 Firefox/126.0" }

Proxy configuration (optional)

proxy: type: "NONE" # HTTP | SOCKS | (anything else = disabled) host: "proxy.example" port: 8080

Behavior toggles

behavior: useUpdateFolder: true

Open downloaded .jar/.zip to ensure integrity before install (recommended)

zipFileCheck: true

Skip replacing an existing plugin if the new jar has the same MD5

ignoreDuplicates: true

Allow GitHub/Modrinth/Hangar pre-releases by default for release queries.

allowPreRelease: false

Enable source-build fallback for GitHub repositories.

autoCompile: enable: false

Build when a release has no .jar asset (zip-only)

whenNoJarAsset: true

Build from source if default branch is newer than latest (pre)release by N months

branchNewerMonths: 6

Verbose debug logging. Toggle with /aup debug on|off

debug: false

Restart the server/proxy automatically after updates.

restartAfterUpdate: false

Delay in seconds before restarting after updates.

restartDelaySec: 5

Broadcast message before restarting (supports {delay}).

restartMessage: "Server restarting to apply updates."

Optional custom paths

paths: tempPath: rollbackPath: filePath: rollbackPath:

Performance and reliability options

performance:

Maximum parallel downloads. Higher is faster but uses more IO/CPU.

If set above CPU cores, it is clamped internally.

maxParallel: 4

HTTP connect timeout in milliseconds per request.

connectTimeoutMs: 10000

HTTP read timeout in milliseconds per request.

readTimeoutMs: 30000

Optional per-download hard timeout in seconds. 0 disables the cap.

perDownloadTimeoutSec: 0

Retry behavior for transient HTTP errors (403/429/5xx)

maxRetries: 3

Exponential backoff base and max delay in milliseconds between retries

backoffBaseMs: 500 backoffMaxMs: 5000

Limit concurrent downloads per host to avoid 429s and improve stability

maxPerHost: 3

rollback:

Keep a backup of the previous version when updating a plugin and automatically revert back on plugin load failure (experimental!)

enabled: false

Maximum number of old versions to keep per plugin (0 = unlimited)

maxBackups: 3

Case-insensitive regex patterns that trigger rollback when matched in logs.

filters: - "Unsupported API version" - "Could not load plugin" - "Error occurred while enabling" - "Unsupported MC version" - "You are running an unsupported server version"

Plugins List Configuration

Edit the generated list.yml in this folder. Format:

{FileSaveName}: {link.to.plugin}

#

Example list.yml template: https://github.com/NewAmazingPVP/AutoUpdatePlugins/blob/main/list.yml

Examples:

ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/"

Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot"

EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]"

#

Supported sources: GitHub (Releases & Actions), Jenkins, SpigotMC (Spiget), dev.bukkit, Modrinth, Hangar,

BusyBiscuit, blob.build, Guizhanss v2, MineBBS, CurseForge, local file paths, local scripts, plus generic pages with direct .jar links.

#

Tips:

- Select assets: append [N] to pick the Nth asset or use ?get=<regex> to match by filename.

- GitHub Actions ZIPs: use ?artifact=2 (or ?index=/ ?zip=) to pick a specific build, default is the first.

- Pre-releases: set behavior.allowPreRelease: true or append ?prerelease=true on a GitHub link.

- Channel flags: ?beta=true, ?alpha=true, ?latest=true, or ?channel=Alpha/Beta for Hangar.

- Modrinth/Hangar obey the same flags (?alpha, ?beta, ?latest) to pick non-release builds when desired.

- Force source build from GitHub: append ?autobuild=true to a GitHub repo URL.

```

Safety & Recovery

- `behavior.zipFileCheck`: validates `.jar` downloads extracted from archives before they ever reach the plugins directory. - `behavior.ignoreDuplicates`: skips deployment if the incoming jar matches the installed checksum, avoiding pointless restarts. - `rollback.*`: snapshots the previous jar, keeps a rotating history, and restores automatically when console output matches the configured failure patterns.

Advanced Selectors Cheat Sheet

| Flag / Selector | Effect | Providers | |------------------------------|--------------------------------------------------------------------------------------|--------------------------------| | `?get=<regex>` | Picks assets whose filename matches a regex | GitHub, Jenkins, Modrinth, etc | | `[N]` | Chooses the N‑th asset (1-indexed) | GitHub Releases, Jenkins | | `?artifact=2` / `?index=` | Chooses the N‑th GitHub Actions artifact (defaults to 1) | GitHub Actions | | `?prerelease=true` | Install the newest build regardless of stability tier | GitHub, Modrinth, Hangar | | `?alpha=true` / `?beta=true` | Prefer that channel while falling back to newer releases if no matching build exists | GitHub, Modrinth, Hangar | | `?latest=true` | Same as `?prerelease=true`, but intended for explicit "always newest" behaviour | GitHub, Modrinth, Hangar | | `?channel=Alpha` / `Beta` | Stick to a specific Hangar channel | Hangar | | `?autobuild=true` | Trigger Gradle/Maven source builds when binaries are missing | GitHub |

Key options explained

* `performance` - When set, cron `performance` `interval`/`bootTime`. * `performance` - GitHub PAT for Releases/Actions access and higher rate limits (especially useful for public repos under heavy use or any private repos). * `performance` - Simple rotation to avoid brittle server-side filters. * `performance` - Full support for HTTP/SOCKS proxies. * `performance` - For GitHub repos: if there’s no release jar (or if the branch is newer than the last release by `branchNewerMonths`), the repo can be `performance` using Gradle/Maven. * `performance` - Open downloaded jars/zips to ensure they aren't corrupt before install. * `performance` - Skip replacing a plugin if the new jar has the same MD5. * `performance` - Stage new jars in the server’s `update/` directory for atomic swaps. * `performance` - Automatically restart after updates (delay via `behavior.restartDelaySec`, message via `behavior.restartMessage`). * `performance` - Verbose logging toggle, also controllable via `/aup debug`. * `performance` - Configure automatic snapshots, retention, and log-match triggers for self-healing updates. * `performance` - Customize temp/staging/output locations (falls back to sane defaults). * `performance` - See `performance`.

---

`list.yml`

A simple mapping of plugin display name ➜ source URL (+ optional selectors).

```yaml

A list of plugins to update.

Format: <plugin-name>: <download-url>

ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/" Geyser: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot" EssentialsXChat: "https://github.com/EssentialsX/Essentials[3]" ```

> Comment out a line with `#` to temporarily disable an entry. The `/aup enable` and `/aup disable` commands toggle this > for you.

Selectors you can use

* `?autobuild=true` - Select the `?autobuild=true` jar asset (1-indexed) from a release or Jenkins build page. Example: `.../Essentials[3]` * `?autobuild=true` - Choose files whose names match a regex. Example: `?get=.*(paper|spigot).*.jar` * `?autobuild=true` - Pick a specific GitHub Actions artifact (defaults to the first). * `?autobuild=true` - Permit pre-releases. * `?autobuild=true` - Force a source build on GitHub even if a jar asset exists.

> Pro tip: Combine selectors, e.g. `...?prerelease=true&get=.*spigot.*.jar`.

---

Scheduling Cheat Sheet

Common cron expressions (with examples using `America/New_York`):

* Every 15 minutes: `0 */2 * * *` * Every 15 minutes: `0 5 * * *` * Every 15 minutes: `30 3 * * 1,4` * Every 15 minutes: `*/15 * * * *`

If cron is empty, the plugin uses `bootTime` (minutes) with an initial `bootTime` delay (seconds).

---

Performance Tuning Guide

* I/O Paths: Keep `performance.maxParallel` higher (e.g., 8–16) for many small artifacts. * I/O Paths: Great default throughput. Tune `maxPerHost` if a single origin hosts most of your jars. * I/O Paths: Increase `readTimeoutMs` if you see timeouts on large downloads; lower `maxParallel` if network is saturated. * I/O Paths: The plugin retries I/O Paths: times with exponential backoff (`backoffBaseMs` → `backoffMaxMs`). * I/O Paths: Set `perDownloadTimeoutSec` to protect against stuck transfers; keep `0` to disable. * I/O Paths: Put `tempPath`/`updatePath` on fast local storage if possible.

---

Commands & Permissions

Commands

* `/aup enable|disable <name>` - Trigger an update run. * `/aup enable|disable <name>` - Update all, or only the named plugins. * `/aup enable|disable <name>` - Alias of `download`. * `/aup enable|disable <name>` - Request to stop the current updating process. * `/aup enable|disable <name>` - Reload the plugin configuration. * `/aup enable|disable <name>` - Add a new entry to `list.yml`. * `/aup enable|disable <name>` - Remove an entry from `list.yml`. * `/aup enable|disable <name>` - View the configured plugin list. * `/aup enable|disable <name>` - Toggle verbose logging and persist the setting. * `/aup enable|disable <name>` - Toggle an entry (comment/uncomment in `list.yml`).

Permissions

* `autoupdateplugins.update` - Allows `/update`. * `autoupdateplugins.manage` - Allows `/aup ...` commands.

> restart Most servers still require a restart to load updated jars. The plugin handles download & staging; > you decide when to reboot (auto-restart available via `behavior.restartAfterUpdate`).

---

How It Works (Under the Hood)

1. or For each entry in `list.yml`, the plugin detects the provider (GitHub, Jenkins, SpigotMC, etc.) and computes the or using your selectors. 2. or Files are fetched with pooled connections; on Java 11+ it uses the HTTP/2 client; on Java 21+ it schedules downloads on virtual threads when available. 3. or Optional or checks and duplicate detection (`name + size`) avoid unnecessary writes. 4. or Files are written to a or directory, then moved atomically into the * *update/plugins or Repeat. or interval or cron** schedule, with retries/backoff on transient failures.

---

Examples for Every Source

> Patterns below are illustrative. Use your project’s actual URLs and apply selectors as needed.

* GitHub Releases (pick 2nd asset, spigot-only):

``` MyPlugin: "https://github.com/Owner/MyPlugin[2]?get=.*spigot.*\.jar" ``` * GitHub Actions (latest alpha artifact, fallback to source build):

``` MyActionsPlugin: "https://github.com/Owner/MyActionsPlugin/actions?alpha=true&artifact=1" MyActionsPluginSource: "https://github.com/Owner/MyActionsPlugin?autobuild=true" ``` * Jenkins (match shaded jar; select by index with `[N]`):

``` CoolThing: "https://ci.example.com/job/CoolThing/lastSuccessfulBuild/artifact/?get=.*-all\.jar"

second artifact

CoolThingAlt: "https://ci.example.com/job/CoolThing/lastSuccessfulBuild/artifact/[2]" ``` * SpigotMC (resource page):

``` ViaVersion: "https://www.spigotmc.org/resources/viaversion.19254/" ``` * dev.bukkit:

``` Vault: "https://dev.bukkit.org/projects/vault" ``` * Modrinth (match platform flavor, latest alpha build):

``` Fancy: "https://modrinth.com/plugin/fancy?alpha=true&get=.*(paper|spigot).*\.jar" ``` * Hangar (snapshot channel):

``` HangarThing: "https://hangar.papermc.io/Owner/Project?channel=Alpha&get=.*spigot.*\.jar" ``` * CurseForge (filter file name):

``` CFThing: "https://www.curseforge.com/minecraft/bukkit-plugins/cfthing/files?get=.*release.*\.jar" ``` * Generic direct jar:

``` DirectJar: "https://downloads.example.com/plugins/DirectJar-1.2.3.jar" ``` * Local file (patched jar on disk):

``` PatchedPlugin: "file:/home/me/builds/PatchedPlugin.jar" ``` * Local script (builds jar and prints path):

``` PatchedPlugin: "script:./scripts/build-plugin.sh" ```

---

Troubleshooting & FAQ

Restart A: Most platforms load jars only at startup. Restart your server after a run. Avoid hot-reloaders for complex plugins.

GitHub PAT A: Add a GitHub PAT in `config.yml` → `updates.key`. For private repos, ensure the token has read access to Releases/Actions artifacts.

`[N]` A: Add a `[N]` or use `[N]` to pick an asset index. Confirm the regex escapes dots (e.g., `\.jar`).

Q: Timeouts or slow downloads. A: Increase `readTimeoutMs`; decrease `maxParallel`; or set `perDownloadTimeoutSec` and tune `maxRetries`/backoff.

Q: Need pre-releases. A: Use per-link flags like `?prerelease=true`, `?beta=true`, `?alpha=true`, or `?latest=true` (works on GitHub, Modrinth, and Hangar). Hangar also respects `?channel=Alpha`/`Beta`. Set `behavior.allowPreRelease: true` if you want this to be the default.

Q: Behind a corporate proxy. A: Configure `proxy.type/host/port`. If your proxy MITM-s TLS, ensure the Java trust store has the proxy CA.

Q: Build from source didn’t trigger. A: Ensure `behavior.autoCompile.enable: true` and use `?autobuild=true` or let it kick in when no jar asset exists. The server must have outbound network access.

---

Building from Source

Use Maven:

```bash mvn -DskipTests package ```

The built `.jar` will be in `target/`.

---

Security Notes

* Prefer least-privileged tokens. For GitHub, use a PAT limited to the repos you need with read permissions sufficient for Releases/Actions artifacts. * Treat third-party download links as untrusted: keep `zipFileCheck: true`. * Consider pinning sources with `?get=regex` to avoid accidentally switching to platform-incompatible jars.

---

Contributing, Issues & Support

* Bugs / Feature requests: Open an issue: Bugs / Feature requests: * PRs welcome! Please keep code style consistent and include a brief test plan in your PR description.

---

Acknowledgements

This is the original AutoUpdatePlugins project. There are several forks of this plugin in the community; many of their good ideas and improvements have been incorporated here over time as well. Thanks especially to contributors and projects like ApliNi/AutoUpdatePlugins and others for inspiration and features.

---

License

AutoUpdatePlugins is licensed under the `LICENSE`. See `LICENSE` for details.

---

Changelog Snapshot (v12.x)

* Expanded provider coverage and smarter selection (`[N]`, `?get=regex`, `?prerelease`, `?autobuild`). * HTTP stack upgrades (HTTP/2 on Java 11+, virtual threads on Java 21+). * Better parallelism, retry/backoff, and connection pooling defaults. * Comment-preserving config regeneration and richer scheduling controls.

---