> ## Documentation Index
> Fetch the complete documentation index at: https://docsgetmyordo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# App Setup

> Learn how to create and configure a GitHub App for Ordo integration. Step-by-step guide to register your Ordo instance with GitHub.

This guide walks you through creating and configuring a GitHub App to enable the Ordo integration. **Start here before deploying or configuring your Ordo instance.**

## Overview

A GitHub App provides secure, granular access to your repositories and enables powerful bidirectional synchronization between Ordo and GitHub:

**Task to GitHub:**

* Automatically create GitHub issues when you create tasks
* Update issue status and priority labels when you change tasks
* Add comments linking to Ordo tasks
* Close/reopen issues based on task status changes

**GitHub to Ordo:**

* Create tasks from GitHub issues
* Sync issue labels (priority, status) to task properties
* Link pull requests to tasks automatically
* Update task status based on branch activity (push, PR open/merge)
* Sync GitHub labels to Ordo task labels

**Automatic Status Transitions:**

* Branch push → Move task to "in-progress"
* PR opened → Move task to "in-review"
* PR merged → Move task to "done"

> [!NOTE]
>
> GitHub Apps are more secure than personal access tokens and provide fine-grained permission control.

> [!WARNING]
>
> **Important**: Complete this GitHub App setup **before** deploying Ordo. You'll need the app credentials during deployment configuration.

## Step 1: Create a GitHub App

**Step 1**

**Navigate to GitHub App Settings**

Go to [GitHub Developer Settings](https://github.com/settings/developers) and click "New GitHub App".

**Step 2**

**Configure Basic Information**

Fill in the basic app information:

* **GitHub App name**: `Ordo-[your-instance-name]` (must be unique across GitHub)
* **Description**: `Ordo project management integration`
* **Homepage URL**: Your planned Ordo instance URL (e.g., `https://Ordo.yourdomain.com`)
* **Webhook URL**: `https://your-Ordo-instance.com/api/github-integration/webhook`
* **Webhook secret**: Generate a secure random string (save this for later)

> [!WARNING]
>
> Replace `your-Ordo-instance.com` with your planned Ordo domain. The webhook URL must be publicly accessible once deployed.

**Step 3**

**Set Repository Permissions**

Configure the following permissions:

| Permission | Access | Purpose |
| - | - | - |
| **Issues** | Read & Write | Create issues, add/remove labels, create comments, close/reopen issues |
| **Pull Requests** | Read | Link pull requests to tasks and track PR status |
| **Metadata** | Read | Access repository information and verify installation |
| **Contents** | Read | Track branch pushes and associate commits with tasks |

> [!WARNING]
>
> **Critical**: Make sure to grant **Write** access to Issues - this is required for the integration to work properly.

> [!NOTE]
>
> Pull Requests permission is optional but recommended for full integration features. Without it, you won't be able to automatically link PRs to tasks or track PR status changes.

**Step 4**

**Subscribe to Webhook Events**

**This step is required for proper integration.** Subscribe to these events:

* **Issues** - To sync issues with tasks (opened, edited, closed, labeled, unlabeled)
* **Issue comments** - To track comments on linked issues
* **Pull requests** - To link PRs to tasks and update task status (opened, closed, reopened, merged)
* **Push** - To automatically update task status based on branch activity

> [!WARNING]
>
> **Required**: You must subscribe to **Issues** events for bidirectional synchronization to work.

> [!NOTE]
>
> **Recommended**: Subscribe to all four event types for full integration features:
>
> * **Issues**: Creates tasks from issues and syncs status/labels
> * **Issue comments**: Tracks GitHub discussions
> * **Pull requests**: Auto-updates task status when PRs are opened/merged
> * **Push**: Moves tasks to "in-progress" when branches are pushed

> [!WARNING]
>
> Without **Push** and **Pull requests** events, automatic status transitions won't work (e.g., moving tasks to "in-progress" on branch push or "done" on PR merge).

**Step 5**

**Create the App**

Click "Create GitHub App" to create your app. You'll be redirected to the app settings page.

## Step 2: Generate Credentials

**Step 1**

**Generate and Download Private Key**

1. Scroll down to the "Private keys" section
2. Click "Generate a private key"
3. Download the `.pem` file - you'll need its contents for configuration

> [!WARNING]
>
> Keep this private key secure! It's used to authenticate your Ordo instance with GitHub.

**Step 2**

**Note Your App Information**

From the app settings page, note down these important values:

* **App ID** (shown at the top of the page)
* **Webhook Secret** (the one you created earlier)
* **Private Key** (contents of the downloaded `.pem` file)

The GitHub App also shows an OAuth **Client ID** and **Client Secret** under "Basic information". Ordo’s **repository integration** does not use those environment variables; they are only relevant if you enable **Sign in with GitHub** using `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` (see [GitHub SSO](https://docsgetmyordo.mintlify.site/core/social-providers/github.md)).

> [!NOTE]
>
> You need **App ID**, **private key**, and **webhook secret** for the [configuration step](https://docsgetmyordo.mintlify.site/core/integrations/github/configuration.md).

## Step 3: Install the App

**Step 1**

**Install on Your Account/Organization**

1. Go to your GitHub App settings page
2. Click "Install App" in the left sidebar
3. Choose your account or organization
4. Select repositories:
   * **All repositories** (if you want integration available for all repos)
   * **Selected repositories** (choose specific repos)

> [!TIP]
>
> You can modify repository access later by going to your [GitHub App installations](https://github.com/settings/installations).

**Step 2**

**Verify Installation**

After installation, you should see your app listed in:

* [Your GitHub App installations](https://github.com/settings/installations)
* The repository's Settings → Integrations & services (for organization repos)

## Security Best Practices

### App Configuration

* **Use descriptive names**: Make it clear the app is for Ordo integration
* **Limit permissions**: Only grant the minimum required permissions
* **Repository scope**: Install only on repositories that need integration

### Credential Management

* **Secure storage**: Store credentials in environment variables or secret management systems
* **Regular rotation**: Generate new private keys periodically
* **Access control**: Limit who has access to the GitHub App settings

## Common Issues

### App Name Already Taken

If your desired app name is taken, try:

* Adding your organization name: `Ordo-mycompany`
* Adding a timestamp: `Ordo-mycompany-2024`
* Using a different naming convention: `mycompany-Ordo`

### Webhook URL Not Accessible

Ensure your Ordo instance is:

* Publicly accessible on the internet
* Using HTTPS (GitHub requires this for webhooks)
* Not behind authentication that would block GitHub's webhook calls

### Permission Issues

Double-check that you've granted:

* **Write** access to Issues (not just Read)
* **Read** access to Pull Requests (for PR linking)
* **Read** access to Metadata and Contents
* Selected the correct repositories during installation

### Webhook Events Not Working

If automatic synchronization isn't happening:

* Verify all webhook events are subscribed (Issues, Issue comments, Pull requests, Push)
* Check webhook deliveries in GitHub App settings for failed deliveries
* Ensure your webhook URL is publicly accessible and using HTTPS

## Next Steps

Now that your GitHub App is created and configured:

1. **[Deploy Ordo](https://docsgetmyordo.mintlify.site/core.md)** - Deploy your Ordo instance with the GitHub App credentials
2. **[Configure GitHub Integration](https://docsgetmyordo.mintlify.site/core/integrations/github/configuration.md)** - Complete the integration setup in your deployed Ordo instance
3. **[Connect Repositories](https://docsgetmyordo.mintlify.site/core/integrations/github/configuration.md#connecting-repositories)** - Link your projects to GitHub repositories

> [!NOTE]
>
> **Important**: Have your GitHub App credentials ready before deployment. You'll need to set them as environment variables during the deployment process.

***

**Need help?** Check our [troubleshooting guide](https://docsgetmyordo.mintlify.site/core/integrations/github/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.