GitHub Integration

Configure GitHub App and repository integration for Jitera Self-Hosted

GitHub integration enables connecting GitHub repositories as code sources within Jitera projects. Users can clone, push, and sync repositories directly from the Jitera UI.

---

Overview

GitHub integration provides:

• Repository Access: Clone, push, and manage repositories from Jitera projects
• Webhooks: Automated triggers for code synchronization on push events

---

Prerequisites

• A GitHub account with permission to create GitHub Apps (organization owner or personal account)
• The main domain hostname for your Jitera deployment (e.g., app.example.com)

---

GitHub App Setup

The steps below are provided as an example. Refer to the GitHub App documentation for the most up-to-date procedure.

Step 1: Create a GitHub App

1. Go to GitHub > Settings > Developer settings > GitHub Apps
2. Click New GitHub App
3. Configure the following fields:

Field	Value
GitHub App name	A descriptive name (e.g., Jitera - YourCompany)
Homepage URL	https://<main-domain>
Callback URL	https://<main-domain>/p/callback/github
Setup URL (optional)	https://<main-domain>/p/callback/github
Request user authorization (OAuth) during installation	Check
Webhook Active	Check if you want webhook integration
Webhook URL	https://<main-domain>/github_webhooks (if webhooks enabled)

Replace <main-domain> with your Jitera main domain hostname (e.g., app.example.com).

Request user authorization (OAuth) during installation must be enabled. This allows Jitera to obtain an OAuth token for each user during the app installation flow, which is required for repository operations on behalf of the user.

Step 2: Configure Permissions

Under Permissions & events, set the following permissions:

Repository Permissions

Permission	Access	Purpose
Administration	Read & write	Manage repository settings and collaborators
Contents	Read & write	Clone and push repository code
Metadata	Read-only	Access repository metadata (mandatory, auto-selected)
Pull requests	Read & write	Create and manage pull requests
Webhooks	Read & write	Manage repository webhooks
Workflows	Read & write	Update GitHub Actions workflow files

Organization Permissions

Permission	Access	Purpose
Administration	Read-only	Read organization settings
Members	Read-only	List organization members and teams
Webhooks	Read & write	Manage organization webhooks

Step 3: Generate Credentials

1. After creating the app, note the App name displayed at the top
2. Copy the Client ID from the app’s general settings
3. Click Generate a new client secret and copy the secret

The client secret is only shown once. Save it securely before leaving the page.

Step 4: Install the App

1. From the GitHub App settings, click Install App in the left sidebar
2. Choose the organization or personal account
3. Select All repositories or choose specific repositories

---

Helm Configuration

Configure the GitHub App credentials in your Helm values:

credentials:
  github:
    app_name: "<your-github-app-name>"
    client_id: "<your-client-id>"
    client_secret: "<your-client-secret>"
  git_webhook_secret: "<your-webhook-secret>"

Key	Description
credentials.github.app_name	The GitHub App name (used for app installation links)
credentials.github.client_id	The Client ID from the GitHub App settings
credentials.github.client_secret	The client secret generated in Step 3
credentials.git_webhook_secret	Shared secret for webhook signature validation

Webhook Secret

Generate a secure webhook secret:

openssl rand -hex 32

This secret must match between the Jitera Helm values (credentials.git_webhook_secret) and the GitHub App webhook configuration.

---

Verification

After deploying with the GitHub credentials configured, connect a GitHub repository to a project to verify the integration. See Code Sources for the in-app connection steps.

---

Troubleshooting

Authorization Callback Error

Symptoms: Error page after GitHub redirects back to Jitera

Solutions:

1. Verify the callback URL in the GitHub App matches exactly:

   https://<main-domain>/p/callback/github
   

2. Check for trailing slashes or protocol mismatches (must be https)

3. Verify credentials are correctly set in the deployment:

   kubectl exec -it deploy/jitera-automation-rails -n jitera -- env | grep GITHUB
   

Repository Access Denied

Symptoms: Cannot clone or push to a repository

Solutions:

1. Verify the GitHub App is installed on the repository’s organization or account
2. Check that the repository is included in the app’s installation (if not using “All repositories”)
3. Verify the app has the required permissions (Contents: Read & write)

Webhook Not Triggering

Symptoms: Code changes in GitHub are not reflected in Jitera

Solutions:

1. Check webhook delivery status in the GitHub App settings:

   • GitHub App > Advanced > Recent Deliveries

2. Verify the webhook URL is accessible from the internet:

   curl -I https://<main-domain>/github_webhooks
   

3. Verify the webhook secret matches between GitHub and Jitera:

   kubectl exec -it deploy/jitera-automation-rails -n jitera -- env | grep WEBHOOK
   

4. Check automation service logs:

   kubectl logs deploy/jitera-automation-rails -n jitera | grep -i webhook
   

---

Related Documentation

GitLab Integration

Configure GitLab integration

Integrations Overview

All available integrations

Requirements

Deployment requirements