# GitHub Issues

Configure GitHub Issues integration with Risotto

## Overview

The GitHub Issues integration creates a GitHub issue for every ticket Risotto handles in a configured department — useful for engineering-facing departments (like internal tooling or DevEx requests) that already track work as GitHub issues.

> **Note:** GitHub sync is **one-way**: Risotto creates issues, posts ticket replies as
> comments on them, and closes them when the ticket is resolved. Changes made
> directly on the GitHub issue (closing it, commenting, relabeling) do not sync
> back to the Risotto ticket.

## Prerequisites

Before connecting, make sure you have:

1. **A GitHub account that can install GitHub Apps** on the organization or account that owns the repository. Risotto syncs through the Risotto GitHub App, which your org installs once. Every department that syncs to GitHub uses that installation.
2. **The repository** issues should be created in (owner and repository name). It must belong to the account the app is installed on, and the app must have access to it.
3. **Permission to change the department's settings** in Risotto: an Org Admin, a Manager, or a Supervisor of the department

## Configuration

| Field          | Required | Description                                            |
| -------------- | -------- | ------------------------------------------------------ |
| **Repository** | Yes      | The `owner/repository` new issues should be created in |

## Setup Process

### Step 1: Configure a Department

1. **Open your department**

   In your Risotto dashboard, go to **Settings**. Under **Departments**, click a
   department, then click **Ticket Sync**.

2. **Add GitHub ticket sync**

   Click **Add ticket sync** and select **GitHub Issues**. **Add ticket sync**
   shows only while the department has no ticket sync: a department syncs with
   one ticketing system.

   *Product example: The Add Ticket Sync for IT dialog, listing the ticketing integrations, with GitHub Issues ringed.*

3. **Install the GitHub App**

   If your org hasn't installed the Risotto GitHub App yet, Risotto takes you
   to GitHub. Install the app on the account that owns the repository, and give
   it access to the repository. You return to the department's **Ticket Sync**
   page, with the GitHub dialog open.

   If the app is already installed, **GitHub Issues** shows **OAuth token
   configured** and opens the dialog directly.

4. **Enter the repository**

   In the **Configure GitHub for \<department>** dialog, enter the
   **Repository** (`owner/repository`) and click **Save**.

   *Product example: The Configure GitHub for IT dialog, with the repository northwind/it-requests filled in, and Save.*

5. **Turn on sync**

   The **Ticket Sync** page now shows the department's sync settings and a
   **GitHub Settings** card with the **Repository**. Make sure **External
   ticket sync enabled** is on.

   *Product example: The IT department's Ticket Sync page with GitHub syncing to northwind/it-requests, and External ticket sync enabled.*

   To create issues only for tickets that escalate, turn on **Only sync
   escalated tickets**.

### Step 2: Test the Integration

Create a test ticket through Risotto and confirm a matching issue appears in the configured repository. Then reply to the ticket in Risotto and confirm the reply appears as a comment on the GitHub issue.

## What Syncs to GitHub

- **Ticket creation** — a new issue is created for every ticket in the department. If **Only sync escalated tickets** is on, Risotto creates the issue when the ticket escalates.
- **Title and description** — changes to the ticket's title and description update the issue
- **Comments** — new replies on the Risotto ticket are added as comments on the GitHub issue, each starting with the author's name. Internal comments don't sync.
- **Resolution** — when the ticket is resolved or closed, Risotto closes the issue

Risotto posts issues and comments as the GitHub App.

## Troubleshooting

### Issues or comments stop syncing with an authentication error

The Risotto GitHub App was likely uninstalled or suspended, or lost access to
the repository. Your Risotto admins receive a **GitHub connection needs to be
reconnected** notification. In GitHub, check that the app is installed on the
account that owns the repository and has access to it.

To reinstall the app from Risotto, open the menu on the department's **GitHub
Settings** row and click **Disconnect...**, then add the GitHub Issues ticket
sync again. When the last department that syncs to GitHub disconnects,
Risotto drops its link to the org's app installation, so adding the sync
again takes you to GitHub to install the app.

### Issue not created for a new ticket

Confirm **External ticket sync enabled** is on for the department and the
repository name is correct (`owner/repository`, exactly as it appears in the
GitHub URL). The repository must belong to the account the GitHub App is
installed on.

## Related Integrations

- [Ticketing Integrations Overview](https://www.tryrisotto.com/docs/integrations/ticketing/overview)
- [Asana Integration](https://www.tryrisotto.com/docs/integrations/ticketing/asana)

Source: https://www.tryrisotto.com/docs/integrations/ticketing/github
