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”

GitHub Apps are more secure than personal access tokens and provide fine-grained permission control.

Important: Complete this GitHub App setup before deploying Ordo. You’ll need the app credentials during deployment configuration.

Step 1: Create a GitHub App

1. Navigate to GitHub App Settings

   Go to GitHub Developer Settings and click “New GitHub App”.

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)

   Replace your-Ordo-instance.com with your planned Ordo domain. The webhook URL must be publicly accessible once deployed.

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

   Critical: Make sure to grant Write access to Issues - this is required for the integration to work properly.

   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.

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

   Required: You must subscribe to Issues events for bidirectional synchronization to work.

   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

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

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

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

   Keep this private key secure! It’s used to authenticate your Ordo instance with GitHub.

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

   You need App ID, private key, and webhook secret for the configuration step.

Step 3: Install the App

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)

   You can modify repository access later by going to your GitHub App installations.

2. Verify Installation

   After installation, you should see your app listed in:

   • Your GitHub App 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 - Deploy your Ordo instance with the GitHub App credentials
2. Configure GitHub Integration - Complete the integration setup in your deployed Ordo instance
3. Connect Repositories - Link your projects to GitHub repositories

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.