WordPress.org Integration
If you publish your plugin on WordPress.org, Troy Server can sync your releases automatically. Enter your plugin's slug, and Troy Server fetches every available version.
How It Works
When you connect your plugin to WordPress.org:
- Troy Server queries the WordPress.org Plugins API.
- Troy Server retrieves up to 30 recent versions and their download URLs.
- During scheduled syncs, Troy Server checks for new releases.
- Troy Server downloads new versions automatically based on your auto-process settings.
Connect Your Plugin
Your plugin on WordPress.org needs a Troy header pointing to your Troy Server. You can find the header at Troy Server → Setup → Server Info. See Troy Headers.
Register Your Plugin
In your WordPress admin:
- Go to Repo Plugins → Add New Plugin.
- In the editor sidebar, register a plugin slug at Plugin Settings.
Note:
Use the same slug from WordPress.org. Slug migrations are on the roadmap, but using a different slug may cause confusion and untested side effects.
Test Your Plugin Header
You can skip the following steps, but triple-check that your header is correct if you do.
Verify that your plugin's Troy header works before publishing it to WordPress.org:
- Copy your Troy header value from Troy Server → Setup → Server Info.
- Add the header to your plugin's main PHP file.
- Build a plugin ZIP.
- Upload the ZIP in the Plugin Versions panel of the plugin you just registered.
If the upload succeeds, your header is correct. If it fails or you get a "repository mismatch" warning, fix the header before proceeding.
Wrong Header = Orphaned Users:
If you upload a wrong header to WordPress.org, users who already have Troy Client installed will never receive updates from you again.
Connect to WordPress.org
- Go to Integrations in the sidebar.
- Click Configure next to WordPress.org.
- Enter your plugin's slug.
- Click Connect.
The slug is the URL-safe name from your plugin's WordPress.org page. For example, if the URL is https://wordpress.org/plugins/hello-dolly/, the slug is hello-dolly.
Choose Auto-Process Settings
Select what Troy Server processes automatically:
| Setting | Behavior |
|---|---|
| All | Processes stable and beta releases. |
| Tag | Processes only stable releases. |
| Beta | Processes only beta releases. |
| None | Fetches tags but does not process them. |
Save the post to apply your settings. You can change this later if needed.
Version Detection
Troy Server determines whether a release is stable or beta based on the version string:
- Stable:
1.0.0,2.3.1. - Beta:
1.0.0-beta,2.0.0-RC1,1.5.0-alpha2.
Troy Server categorizes versions automatically.
Three-Part Versions Required:
Troy Server requires three-part semantic versions (major.minor.patch). Two-part versions like 1.0 or 2.0-RC1 are ignored during import. If your WordPress.org plugin uses two-part versioning, those releases will not appear in Troy Server.
Sync Schedule
WordPress.org connections sync on the same schedule as other external sources. By default, Troy Server checks every 30 minutes via WordPress cron.
To trigger an immediate sync, click Process All New in the plugin's Integrations section.
Note:
Your plugin must include a Troy header pointing to your Troy Server. Versions without the header cannot be imported.
Redistribution Risk:
If someone working for WordPress.org modifies your plugin and keeps the Troy header intact, Troy Server will redistribute that version automatically. If they change the header, Troy Server marks the version as Unreleased instead of redistributing it. Consider whether this risk is acceptable for your use case.
Troubleshooting
Plugin Not Found
The slug does not match any plugin on WordPress.org. Double-check the spelling. The slug appears in the plugin's URL on wordpress.org, not in its display name.
API Request Failed
WordPress.org returned an error. Wait a few minutes and try again. If the error persists, check that your server can reach api.wordpress.org.
No Versions Found
Your plugin exists on WordPress.org but has no published versions. Check your plugin's status on WordPress.org.
Updated Tag Not Detected
WordPress.org does not expose reliable checksums for plugin versions. If you update an existing tag (same version number, new code), Troy Server cannot detect the change automatically.
To reimport a tag manually:
- Go to Repo Plugins and click the plugin.
- Scroll to Integrations.
- Click Configure next to WordPress.org.
- Click Import next to the tag you want to reprocess.
Next Steps
- GitHub Integration — Connect private repositories with token authentication.
- Troubleshooting — Resolve common Troy Server issues.
