GitHub Integration
If you host your plugin on GitHub, Troy Server can sync your releases automatically. Enter your repository, and Troy Server polls for new tags and imports them.
How It Works
When you connect your plugin to GitHub:
- Troy Server queries the GitHub Tags API for up to 30 recent tags.
- During scheduled syncs, Troy Server checks for new or changed tags.
- Troy Server downloads new versions automatically based on your auto-process settings.
- Downloaded ZIPs are validated, extracted, and stored.
Troy Server downloads the source code zipball from each tag. This ZIP contains your repository as GitHub sees it — which means your .gitignore controls what ships. Make sure that test files, build configs, and anything you don't distribute are listed in .gitignore before tagging a release.
Release Asset Support Planned:
Support for targeting release asset ZIPs is on the roadmap — enabling monorepos and custom build pipelines to work seamlessly with Troy Server.
Connect Your Plugin
Your plugin needs a Troy header pointing to your Troy Server. You can find the header at Troy Server → Setup → Server Info. See Plugin 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.
Test Your Plugin Header (Recommended)
You can skip this test, but triple-check that your header is correct if you do.
Verify that your plugin's Troy header works before pushing it to GitHub:
- 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 already distribute your plugin through GitHub and push a version with a wrong Troy header, users who have Troy Client installed will never receive updates from you again.
Connect to GitHub
- Go to Integrations in the sidebar.
- Click Configure next to GitHub.
- For private repositories, add a Personal Access Token (PAT) first. Click the link in the panel to generate one — Troy Server pre-fills the token name and required scope (
contents: read). Set the expiration (365 days recommended), copy the token, and paste it into the Personal Access Token field. - Enter your repository as
owner/repoor a full GitHub URL. - Click Connect.
For public repositories, the token is optional — GitHub allows unauthenticated access to public tags. Rate limits only become a concern once you connect more than 60 plugins without tokens.
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. Tags that do not match a recognized version pattern are ignored.
Three-Part Versions Required:
Troy Server requires three-part semantic versions (major.minor.patch). Two-part tags like v1.0 or 2.0-RC1 are ignored during import.
Sync Schedule
Troy Server checks for new tags every 30 minutes via WordPress cron and processes up to 2 queued tags per minute.
To trigger an immediate sync, click Process All New in the plugin's Integrations section.
If you overwrite a tag version number with new code, Troy Server detects the hash-change and reimports the tag on the next sync cycle.
Note:
Your plugin must include a Troy header pointing to your Troy Server. Versions without the header are marked as blocked. Versions whose header points to a different server are marked as unreleased.
Troubleshooting
Repository Not Found
The owner/repo format does not match an accessible repository. Double-check the spelling. If the repository is private, ensure that your PAT has contents: read permission and has not expired.
No Tags Found
Your repository exists but has no version-like tags. Push at least one three-part semantic version tag (e.g., v1.0.0).
Rate Limiting
Add a Personal Access Token — even for public repositories. A token increases GitHub's API rate limit from 60 to 5,000 requests per hour.
Updated Tag Not Detected
Troy Server compares commit SHAs, so force-pushed tags are detected automatically. If a tag still does not appear, click Refresh in the Integrations panel to force a fresh fetch.
To reimport a tag manually:
- Go to Repo Plugins and click the plugin.
- Scroll to Integrations.
- Click Configure next to GitHub.
- Click Import next to the tag you want to reprocess.
Security Notes
- Use fine-grained tokens with
contents: readscope only. - Set a shorter token expiration if your security policy requires it, and rotate regularly.
- Troy Server stores the token in your WordPress database. Limit database access to trusted users.
- Revoke and replace the token if you suspect it has been exposed.
Next Steps
- WordPress.org Integration — Sync releases from the WordPress.org plugin directory.
- Troubleshooting — Resolve common Troy Server issues.
