> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/ticketing-and-messaging/ticket-management/github-issues.md).

# GitHub Issues

GitHub Issues integration enables you to create and manage GitHub tickets for security issues detected by OX. Tickets can be created manually or automatically using workflows.

OX can automatically select the GitHub organization and repository associated with each finding, allowing a single workflow to create tickets across multiple repositories.

The integration also supports automatic status updates, comments, SLA-related dates, and priority synchronization to help development and security teams track remediation directly in GitHub.

Integrating OX Security with GitHub enhances your software development lifecycle by embedding security insights directly into your GitHub workflow, as follows:

* **Automated Issue Tracking**: Security findings detected by OX Security can be logged as issues, ensuring that vulnerabilities are tracked and addressed promptly.
* **Seamless Collaboration**: Developers, security teams, and project managers can manage security-related tasks within their existing GitHub environment, streamlining the remediation process and improving team collaboration.
* **Improved Security Visibility**: The integration provides clear visibility into security risks within the development pipeline, helping teams prioritize and resolve issues more efficiently.
* **Enhanced Compliance Management**: Organizations can ensure compliance by tracking security-related tasks alongside other development activities, simplifying audits and reporting.

## Adding GitHub Tickets

After [establishing the connection with GitHub](#connecting-to-github-issues), you can create tickets to track and remediate security issues detected by OX.

You can create GitHub Issues tickets using one of the following methods:

* Manually create a ticket for an individual issue from the OX Issues page.
* Automatically create tickets using OX workflows.

Workflows also support dynamic repository selection, allowing you to create tickets across multiple repositories without configuring a separate workflow for each repository.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-d1ab936b7c3d0b7f33dd7b1da9d15d21cd27803c%2FGH_WF.png?alt=media&amp;token=a31a7bfe-0db5-4557-b90f-fc993c0ee931" alt="" width="202"><figcaption></figcaption></figure>

**To add a new GitHub ticket in OX:**

1. In the **Issues** page, identify and select the issue for which you want to add a ticket in GitHub.
2. Select the GitHub icon.
3. Set the ticket parameters in the **Create GitHub Issue Ticket** dialog.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-4f722c5bbd68d1eeae813b77f7b6a6a3460816a4%2FModern_GitHub_Issue_Action_Settings_Modal.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

| Parameter    | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| Title        | The title of the GitHub ticket, describing the security issue detected by OX. |
| Organization | Select the GitHub organization where the ticket is created.                   |
| Project      | Select the GitHub Project to associate with the ticket.                       |
| Labels       | Select the GitHub labels to apply to the ticket.                              |
| Repository   | Select the GitHub repository where the ticket is created.                     |
| Assigned To  | Select the GitHub user to assign to the ticket.                               |

4. Select **CREATE TICKET**.

The new ticket appears in GitHub.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-383c4854ec7c28619066ae8029fc019ba4749091%2FGH_final_ticket%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### Automatically creating GitHub tickets using workflows

Use OX workflows to automatically create GitHub Issues tickets when security issues meet specific conditions. A single workflow can create tickets across multiple repositories by dynamically selecting the organization and repository associated with each finding.

To automatically create GitHub Issues tickets:

1. Go to **Workflows**.
2. Create a new workflow or edit an existing workflow.
3. Configure the trigger and conditions that determine when the workflow runs.
4. Add an **Action** and select **GitHub Issues**.
5. In the **Action Settings** dialog, configure the ticket parameters described in the following table.

| Parameter                                                                      | Description                                                                                                                            |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Title                                                                          | The title of the GitHub ticket. Editing the summary overrides the issue summary for all selected issues.                               |
| Organization                                                                   | Select a GitHub organization or `@findingOrganization` to automatically use the organization associated with each finding.             |
| Repository                                                                     | Select a specific repository or `@findingRepository` to automatically create the ticket in the finding's associated repository.        |
| Issue Type                                                                     | Select the GitHub issue type, such as Bug.                                                                                             |
| Project                                                                        | Select a GitHub Project to associate with the ticket, when available.                                                                  |
| Assign To                                                                      | Select GitHub users or workflow parameters to assign the ticket dynamically.                                                           |
| Fallback "Assign To"                                                           | Select alternative assignees to use when the primary assignees cannot be resolved.                                                     |
| Labels                                                                         | Specify labels to apply to the ticket. When using `@findingRepository`, OX looks up the specified labels in each finding's repository. |
| Always create a ticket (even if the issue already has an attached open ticket) | Create another ticket even if the OX issue already has an attached open ticket. Disabled by default.                                   |
| Apply to                                                                       | Select which issues trigger ticket creation, such as New Issues or Updated Issues.                                                     |

6. Select **Add**.
7. Save and enable the workflow.

OX automatically creates GitHub Issues tickets when the configured workflow conditions are met.

#### Selecting organizations and repositories

The Organization and Repository fields determine where GitHub Issues tickets are created.

You can select a specific organization and repository or use workflow parameters to dynamically select the repository associated with each finding.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-1ac6ac8e84dd1f474c34d4df21425820813b2d05%2FGitHub_ticketing1.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

| Configuration                                   | Behavior                                                                                             |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Specific organization and repository            | Creates tickets in the selected repository.                                                          |
| Specific organization and `@findingRepository`  | Creates each ticket in the repository associated with the finding, within the selected organization. |
| `@findingOrganization` and `@findingRepository` | Automatically selects the organization and repository associated with each finding.                  |

When `@findingOrganization` is selected, the Repository field is automatically set to `@findingRepository`.

The GitHub connection must have access to the selected organization and repository.

> **Note:** Issues without an associated source repository, such as Cloud Security or Container Security issues, require a specific repository to be selected.

#### Assigning tickets dynamically

The Assign To field supports workflow parameters that automatically assign GitHub Issues tickets to users associated with the OX issue or application.

Type `@` in the Assign To field to display the available parameters.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-4ae27982693f18605443ee85ca5ee6f8e290d0db%2FGitHub_ticketing2%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

| Parameter                | Description                                               |
| ------------------------ | --------------------------------------------------------- |
| `@issueOwnerEmail`       | The email address of the OX issue owner.                  |
| `@appOwnerDevEmail`      | The email address of the application's development owner. |
| `@appOwnerBusinessEmail` | The email address of the application's business owner.    |
| `@appOwnerSecurityEmail` | The email address of the application's security owner.    |
| `@appOwnerWatcherEmail`  | The email address of the application's watcher.           |

OX resolves the assignees when the ticket is created. Each assignee must correspond to a GitHub user with write access to the target repository.

If the primary assignees cannot be resolved, OX uses the Fallback "Assign To" field. If no valid assignee is found, the ticket is created without an assignee.

GitHub supports up to 10 assignees per issue.

#### Applying labels across repositories

GitHub labels are defined at the repository level, so different repositories may have different labels.

When using `@findingRepository`, OX looks up the specified label in each finding's repository instead of retrieving labels from all repositories during workflow configuration.

**To apply labels dynamically:**

1. In the **Action Settings** dialog, select **Labels**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-91907ff2e933625bed2fb56a6db0157342fc3c03%2FGitHub_ticketing3.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

2. Enter the label name.
3. Press **Enter**.

OX looks up the specified label in the target repository when creating the ticket.

### Synchronizing GitHub Issues tickets

OX can automatically update linked GitHub Issues tickets when the corresponding security issues change.

Depending on the configured settings, OX can:

* Add comments when issues are resolved, excluded, or updated.
* Close GitHub tickets when OX issues are resolved, excluded, or removed.
* Reopen GitHub tickets when previously resolved, excluded, or removed issues become active again.
* Populate SLA-related dates in GitHub issue fields.
* Map OX severity levels to GitHub priority values and keep priorities synchronized.

Configure these options under Settings > Ticketing and Messaging Settings > GitHub Issues.

> **Note:** Synchronization is one-way, from OX to GitHub Issues. Changes made directly in GitHub do not update the corresponding OX issues.

## Connecting to GitHub Issues

### Prerequisites

GitHub account.

{% hint style="info" %}
GitHub Issues ticketing supports public, private, and internal GitHub repositories. Ticket creation in public repositories is controlled by the GitHub Issues public repository settings to prevent accidental exposure of sensitive security findings.
{% endhint %}

### Connect to GitHub Issues

1. [Get a GitHub token.](https://docs.ox.security/get-started/onboarding-to-ox/source-control/github/github-token/getting-github-tokens.md)
2. In the **OX** platform, go to **Connectors** and search for **GitHub Issues**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-21ff6cf6202d81ab6fb4e5a406bf7e3b890de463%2FGH_issues_icon1%20(1).png?alt=media" alt="" width="86"><figcaption></figcaption></figure>

3. Select **GitHub Issues** and set the following parameters in the **Configure your GitHub Issues credentials** dialog.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-edf2d25777e452f45f6d758877b10a891dd4115a%2FGitHub_ticketing4.png?alt=media" alt="" width="511"><figcaption></figcaption></figure>

| Parameter                  | Description                                                                                                                                                                 |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub Issues Host URL** | The GitHub API base URL. Keep the default [https://api.github.com](https://api.github.com/) for [GitHub.com](http://github.com). GitHub Enterprise Server is not supported. |
| **Token**                  | Paste the GitHub token you have created.                                                                                                                                    |

4. Select **CONNECT**. The success message appears.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ox.security/ticketing-and-messaging/ticket-management/github-issues.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
