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.
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
- API Reference Build custom integrations
- Troubleshooting Common issues and solutions
