These docs have been generated using AI. Expect inaccuracies until we remove this banner.
GitHub Integration
Connect your GitHub repository to Troy Server and automate your release process.
The workflow:
- You push code to GitHub
- You tag a release (e.g.,
v1.3.0) - Troy Server fetches the release automatically
- Your users see the update in their dashboard
No manual uploads. No extra steps.
Setting Up GitHub Integration
Enter Your Repository
On your plugin's edit screen, find the GitHub panel:
- Enter your repository in the format
username/repository - For example:
your-username/my-plugin
Add a Personal Access Token (Optional)
For private repositories, you'll need a GitHub Personal Access Token:
- Go to GitHub Settings Developer Settings Personal Access Tokens
- Create a new token with
reposcope (for private repos) orpublic_repo(for public) - Paste it into Troy Server's GitHub panel
For public repositories, the token is optional but helps avoid rate limits.
Choose Your Tag Strategy
Troy Server looks for tags that look like versions:
v1.0.01.0.0v1.0.0-betarelease-1.0.0
When you push a new tag, Troy Server can automatically fetch that release.
Configure Auto-Process
Set the Auto-process option to control which releases are imported automatically:
| Setting | Behavior |
|---|---|
| All new tags | Import both stable and beta releases |
| Stable releases only | Only import versions without pre-release suffixes |
| Beta releases only | Only import pre-release versions (alpha, beta, rc, etc.) |
| None | Disable automatic imports |
Troy Server checks for new tags every 30 minutes and processes up to 2 tags each minute.
Troy Header Required:
Your plugin must include a valid Troy: header pointing to your repository URL. Without it, the version will be marked as blocked. If the header points to a different repository, the version will be marked as unreleased. This prevents you from sending updates that don't belong to your repository, potentially severing your users' update flow.
See Plugin Headers for details.
Automatic vs Manual Fetching
Automatic (Webhooks)
Set up a webhook to notify Troy Server when you push a tag:
- In GitHub, go to your repository Settings Webhooks
- Add a webhook pointing to your Troy Server's webhook endpoint
- Select "Release" events
When you publish a release, GitHub pings Troy Server, which fetches the ZIP.
Note:
Coming in a future update: One-click webhook setup directly from Troy Server's admin panel.
Manual (On-Demand)
Click Fetch Latest Release in Troy Server's admin. It checks GitHub for the latest tagged release and imports it.
This is useful for:
- Initial imports
- When webhooks are not an option
- Testing the integration
Release Assets vs Source Code
Troy Server can fetch either:
- Release assets ZIP files you upload to a GitHub release
- Source code GitHub's auto-generated ZIP from your tag
If you upload a ZIP asset to your release (recommended), Troy Server uses that. Otherwise, it uses the source code archive.
Why Upload Release Assets?
The source code ZIP includes:
- Test files
- Documentation you don't ship
- Development configs
A release asset lets you ship only what users need.
Tip: Use GitHub Actions to automatically build and attach a clean ZIP to each release.
Directory Structure
Troy Server expects your plugin's main file to be either:
- In the root of the ZIP (e.g.,
my-plugin.php) - In a folder matching the plugin slug (e.g.,
my-plugin/my-plugin.php)
If your repo structure is different, build a ZIP with the correct structure before attaching it to your release.
Troubleshooting
"Repository not found"
- Check the repository name format:
username/repository - If private, ensure your token has
reposcope - Verify the token hasn't expired
"No releases found"
- Make sure you've pushed at least one tag
- Tags must look like versions (
v1.0.0,1.0.0, etc.) - Go to GitHub and check that Releases exist (not just Tags)
Rate limiting
- Add a Personal Access Token (even for public repos)
- Tokens increase your rate limit from 60 to 5,000 requests/hour
Wrong version imported
- Troy Server imports the highest version tag it finds
- If you need a specific version, use Manual Fetch and specify the tag
Security Notes
- Personal Access Tokens are encrypted in the database
- Use fine-grained tokens with minimal scope
- For private repos, create a token with read-only access
- Consider creating a bot account for organizational repositories
What About GitLab or Bitbucket?
Not yet supported. If you need these integrations, open an issue on GitHub.
Next Steps
- Create a Package — Distribute your plugin with Troy Client bundled
- API Reference — Build custom integrations
- Troubleshooting — Common issues and solutions
