# GitHub Ticketing Provider Configuration Guide

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.

## Overview

GitHub Issues uses a **fine-grained personal access token** (PAT) for authentication. The integration communicates with the [GitHub REST API](https://docs.github.com/en/rest) to create, read, update, and comment on issues within a single repository.

## Prerequisites

- 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)


## Authentication Steps

### 1. Create a fine-grained personal access token

1. Sign in to GitHub and navigate to **Settings → Developer settings → Personal access tokens → Fine-grained tokens** (direct link: [github.com/settings/tokens?type=beta](https://github.com/settings/tokens?type=beta)).
2. Click **Generate new token**.
3. Give the token a descriptive name (e.g. `synqly-ticketing-integration`).
4. Under **Repository access**, select **Only select repositories** and choose the repository you want to integrate.
5. 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 |


1. Click **Generate token** and copy the token value immediately — it will not be shown again.


Official reference: [Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#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.


### 2. Identify your target repository

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}`.

## Configure the Integration

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. |


## Troubleshooting

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/repo` value 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-reset` response 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.


## Additional Resources

- [GitHub REST API documentation](https://docs.github.com/en/rest)
- [Managing personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
- [GitHub Issues API reference](https://docs.github.com/en/rest/issues)
- [GitHub API rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)