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

# Configuration & Setup

> Configure Ordo with your GitHub App credentials and connect projects to repositories.

This guide covers configuring Ordo with your GitHub App credentials and connecting projects to repositories.

> [!NOTE]
>
> Make sure you've completed the [GitHub App setup](https://docsgetmyordo.mintlify.site/core/integrations/github/setup.md) before proceeding.

## Environment Variables

Add the following environment variables to your Ordo deployment:

```bash theme={null}
# GitHub App (integration only — repository sync, webhooks)
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
[Full contents of your private key]
...
-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=your-webhook-secret-here

# Optional: GitHub App slug for installation URLs in the UI
GITHUB_APP_NAME=ordo-your-instance-name
```

> [!NOTE]
>
> GitHub sign-in uses separate OAuth variables (`GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`). You can run the integration without enabling GitHub SSO. See [GitHub SSO](https://docsgetmyordo.mintlify.site/core/social-providers/github.md).

### Variable Reference

| Variable | Description | Required | Example |
| - | - | - | - |
| `GITHUB_APP_ID` | Your GitHub App's ID | ✅ | `123456` |
| `GITHUB_PRIVATE_KEY` | Full private key content (with newlines) | ✅ | `-----BEGIN RSA...` |
| `GITHUB_WEBHOOK_SECRET` | Secret for webhook verification | ✅ | `your-secret` |
| `GITHUB_APP_NAME` | App slug for installation URLs in the UI | ⚠️ | `ordo-mycompany` |

> [!WARNING]
>
> `GITHUB_APP_NAME` is optional but recommended. It's used to generate direct installation links in the UI.

## Connecting Repositories

Once your environment variables are configured and your backend is restarted, you can connect projects to GitHub repositories.

**Step 1**

**Navigate to Project Settings**

1. Open your Ordo project
2. Go to **Project Settings**
3. Find the **GitHub Integration** section

**Step 2**

**Connect Repository**

You have two options to connect a repository:

**Option A: Browse Repositories**

1. Click "Browse Repositories"
2. Select from repositories where your GitHub App is installed
3. Click on the desired repository

**Option B: Manual Entry**

1. Enter the **Repository Owner** (username or organization)
2. Enter the **Repository Name**
3. Click "Verify Installation"

**Step 3**

**Verify and Connect**

1. Ordo will verify that your GitHub App has access
2. If successful, click "Connect Repository"
3. You should see a green "Connected" status

> [!TIP]
>
> Once connected, new tasks created in this project will automatically generate GitHub issues!

## Testing the Integration

After connecting a repository, test the integration thoroughly:

**Step 1**

**Test Task to Issue Creation**

Create a new task in your connected Ordo project with:

* A clear title
* A description
* Set priority and status

Navigate to your GitHub repository and verify:

* A new issue was created
* The issue has `priority:*` and `status:*` labels
* A comment links back to the Ordo task

**Step 2**

**Test Automatic Status Transitions**

Test branch-based workflow:

1. Note your task number (e.g., `PROJ-123`)
2. Create and push a branch matching the pattern (e.g., `proj-123`)
3. Verify the task moves to "in-progress"
4. Open a PR from that branch
5. Verify the task moves to "in-review"
6. Merge the PR
7. Verify the task moves to "done"

> [!NOTE]
>
> Default branch pattern is `{slug}-{number}`. You can customize this in project settings.

**Step 3**

**Test Issue to Task Sync**

In GitHub:

1. Create a new issue
2. Add labels like `priority:high` or `status:in-progress`

In Ordo:

* Verify a task was created from the issue
* Check that priority and status match the labels
* Confirm the task links to the GitHub issue

**Step 4**

**Test Label Synchronization**

Test both directions:

1. Change task priority in Ordo → Check issue labels in GitHub
2. Add/remove labels in GitHub → Check task in Ordo
3. Change task status in Ordo → Check if issue is closed/reopened

## Advanced Configuration

### Branch Naming Patterns

Configure how Ordo matches branches to tasks in your project's GitHub integration settings:

**Predefined Patterns:**

* `{slug}-{number}` (default) - e.g., `proj-123`
* `{slug}-{number}-{title}` - e.g., `proj-123-fix-bug`
* `{number}` - e.g., `123`
* `{number}-{title}` - e.g., `123-fix-bug`
* `feature/{slug}-{number}` - e.g., `feature/proj-123`
* `fix/{slug}-{number}` - e.g., `fix/proj-123`

**Custom Regex:**
You can also provide a custom regex pattern for more complex matching.

> [!TIP]
>
> The `{slug}` variable is your project's slug (case-insensitive), `{number}` is the task number, and `{title}` is an optional slug of the task title.

### Status Transition Configuration

Customize when tasks automatically change status:

| Event | Default Status | Customizable |
| - | - | - |
| Branch Push | `in-progress` | ✅ |
| PR Opened | `in-review` | ✅ |
| PR Merged | `done` | ✅ |

Configure these in your project's GitHub integration settings to match your workflow.

> [!WARNING]
>
> Status transitions only apply if the task is not already in "done" status. This prevents accidentally reopening completed tasks.

### Label Synchronization

Ordo automatically creates and syncs these label types:

**System Labels** (managed automatically):

* `priority:low`, `priority:medium`, `priority:high`, `priority:urgent`
* `status:to-do`, `status:in-progress`, `status:in-review`, `status:done`, `status:planned`, `status:archived`

**Custom Labels:**

* Any labels added to GitHub issues (not starting with `priority:` or `status:`) are synced to Ordo
* Labels added in Ordo can be synced to GitHub (if configured)

### Multiple Organizations

If you need to connect repositories from multiple GitHub organizations:

1. Install your GitHub App on each organization
2. Grant appropriate permissions for each organization
3. Each Ordo project can connect to any repository where your app is installed

***

**Having issues?** Check our [troubleshooting guide](https://docsgetmyordo.mintlify.site/core/integrations/github/troubleshooting.md) for common problems and solutions.


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