This guide provides step-by-step instructions for configuring the GitHub Issues ticketing integration with our platform. By following these instructions, you'll be able to connect your GitHub repository to enable issue management and synchronization through Synqly.
GitHub Issues uses a fine-grained personal access token (PAT) for authentication. The integration communicates with the GitHub REST API to create, read, update, and comment on issues within a single repository.
- A GitHub account with access to the target repository
- Permission to create and manage issues in that repository
- Ability to generate personal access tokens (requires account-level settings access)
- Sign in to GitHub and navigate to Settings → Developer settings → Personal access tokens → Fine-grained tokens (direct link: github.com/settings/tokens?type=beta).
- Click Generate new token.
- Give the token a descriptive name (e.g.
synqly-ticketing-integration). - Under Repository access, select Only select repositories and choose the repository you want to integrate.
- Under Repository permissions, grant the following:
| Repository Permission | Access Level | Purpose |
|---|---|---|
| Issues | Read & Write | Create, read, and update issues |
| Metadata | Read-only | Access repository metadata |
- Click Generate token and copy the token value immediately — it will not be shown again.
Official reference: Creating a fine-grained personal access token.
Note: Treat the token as a secret. Rotate it immediately if leaked, and update the credential everywhere it is configured (including Synqly). Fine-grained tokens can be scoped to specific repositories, which limits blast radius compared to classic tokens.
The integration scopes all issue operations to a single repository. You'll need the repository identifier in owner/repo format — for example, my-org/my-repo.
You can find this in the repository URL: https://github.com/{owner}/{repo}.
Create your integration by supplying the following values:
| Parameter | Description |
|---|---|
| Credential | The fine-grained personal access token created above. |
| Repository | Target repository in owner/repo format (e.g. my-org/my-repo). All issue operations are scoped to this repository. |
| URL | Base URL for the GitHub environment. Only required for GitHub Enterprise Server deployments — defaults to https://github.com for GitHub.com users. |
If something fails:
- 401 / Bad credentials: Verify the token has not expired or been revoked. Regenerate it from Settings → Developer settings → Fine-grained tokens if needed.
- 404 / Not Found on repository: Confirm the
owner/repovalue is correct and that the token's repository access includes the target repository. - 403 / Resource not accessible: The token is missing required permissions. Ensure both Issues (Read & Write) and Metadata (Read-only) are granted for the target repository.
- 429 / Rate limit exceeded: GitHub enforces API rate limits (typically 5,000 requests/hour for authenticated requests). Wait for the reset window indicated in the
x-ratelimit-resetresponse header, or review request volume. - URL issues (Enterprise Server): For GitHub Enterprise Server, use the instance's base URL (e.g.
https://github.yourcompany.com). Do not include/api/v3/— the integration appends the correct API path automatically.