Git Integration

oCore integrates with GitHub, GitLab, and Bitbucket to enable automatic deployments when you push code. This page covers connecting repositories, configuring webhooks, setting up branch-to-environment mappings, and using the GitHub App integration for enhanced features.

Connecting a Repository

Supported Providers

Connection Steps

git@github.com:acme/odoo-custom.git

curl -X POST https://ocore.example.com/api/projects/{projectId}/repository \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryUrl": "git@github.com:acme/odoo-custom.git",
    "branch": "main",
    "provider": "github"
  }'

ocore project connect-repo <project-id> \
  --url git@github.com:acme/odoo-custom.git \
  --branch main \
  --provider github

Webhook Configuration

Webhooks notify oCore when code is pushed to your repository. oCore validates the webhook signature and triggers a deployment if the branch has a mapping.

Webhook Endpoints

oCore exposes provider-specific webhook endpoints:

These endpoints are public (no JWT required) -- authentication is done via HMAC signature verification using the webhook secret.

Webhook Events

Configure your webhook to send:

Verifying Webhook Delivery

If deployments are not triggering:

1. Check the webhook delivery logs in your Git provider's settings
2. Look for HTTP 200 responses from oCore
3. Verify the webhook secret matches between the provider and oCore
4. Use the Reconfigure Webhook action to regenerate:

curl -X POST https://ocore.example.com/api/projects/{projectId}/repository/reconfigure-webhook \
  -H "Authorization: Bearer $TOKEN"

Automatic Deployments on Push

When oCore receives a webhook for a push event, it:

1. Extracts the branch name and commit SHA from the payload
2. Looks up branch-to-environment mappings for the project
3. If a mapping exists, triggers a deployment to the mapped environment
4. The deployment follows the standard pipeline (see Deployments)

Example Flow

Developer pushes to `main`
  -> GitHub sends webhook to oCore
    -> oCore finds `main` maps to Production environment
      -> Deployment triggered: build, push, restart
        -> Production instance updated with new code

Branch-to-Environment Mapping

Map Git branches to environments so pushes automatically deploy to the correct target.

Creating Mappings

curl -X PUT https://ocore.example.com/api/projects/{projectId}/branch-mappings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "environmentId": "ENV_UUID"
  }'

ocore project map-branch <project-id> \
  --branch main \
  --environment ENV_UUID

Common Branch Strategies

Listing Mappings

curl https://ocore.example.com/api/projects/{projectId}/branch-mappings \
  -H "Authorization: Bearer $TOKEN"

GitHub App Integration

For enhanced GitHub integration, install the oCore GitHub App on your organization. The GitHub App provides:

• Automatic repository access -- No need to manually add deploy keys
• Enhanced webhook management -- Webhooks configured automatically
• Check runs -- Deployment status reported as GitHub check runs
• Commit status -- Build status shown directly on commits and PRs

Installing the GitHub App

Managing the GitHub App

# View GitHub App configuration
curl https://ocore.example.com/api/settings/github-app \
  -H "Authorization: Bearer $TOKEN"

# List GitHub App installations
curl https://ocore.example.com/api/settings/github-app/installations \
  -H "Authorization: Bearer $TOKEN"

Multiple GitHub Account Support

If your organization manages repositories across multiple GitHub accounts or organizations, oCore supports installing the same GitHub App on each of them. This is common when you have:

• A company GitHub organization for production modules and a separate one for client-specific customizations
• Personal GitHub accounts alongside an organization account
• Separate GitHub organizations per client or business unit

How Multi-Installation Routing Works

Each GitHub App installation is associated with a specific GitHub account (user or organization). When oCore needs to interact with a repository -- for webhooks, check runs, or commit statuses -- it matches the repository owner to the correct installation:

1. oCore extracts the repo owner from the repository URL (e.g., acme from git@github.com:acme/odoo-custom.git)
2. It looks up all active GitHub App installations for your oCore organization
3. It finds the installation whose account_login matches the repo owner (case-insensitive)
4. The matched installation's credentials are used for API calls to that repository

This routing is automatic -- you do not need to manually assign installations to projects.

Adding an Installation

Viewing Installations

The GitHub App settings page shows all active installations with their account name, type (user or organization), and creation date.

# List all installations
curl https://ocore.example.com/api/settings/github-app/installations \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "installations": [
    {
      "installation_id": 12345678,
      "account_login": "acme-corp",
      "account_type": "organization",
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "installation_id": 87654321,
      "account_login": "acme-client-a",
      "account_type": "organization",
      "created_at": "2026-02-20T14:00:00Z"
    }
  ]
}

Removing an Installation

To unlink a GitHub App installation from your oCore organization:

curl -X DELETE https://ocore.example.com/api/settings/github-app/installations/{installationId} \
  -H "Authorization: Bearer $TOKEN"

This soft-deletes the installation record in oCore. To fully uninstall the GitHub App from the GitHub account, visit the GitHub App settings page on GitHub.

Per-Project Routing

Each project in oCore is linked to a repository URL that includes the owner (e.g., acme-corp/odoo-modules). When oCore processes a webhook, creates a check run, or reports a commit status for that project, it automatically selects the installation matching acme-corp.

No per-project configuration is needed -- the routing is derived from the repository URL at runtime.

Push Notifications

oCore can send deployment notifications via push events. Configure notification preferences to receive updates when:

• Deployment starts
• Deployment succeeds
• Deployment fails

See your notification preferences in account settings.

Required Permissions

• Connecting repositories requires manage:projects permission
• Managing webhooks requires manage:projects permission
• GitHub App installation requires manage:org_settings permission
• Branch mappings require manage:projects for creation, view:projects for viewing

Troubleshooting

Webhook returns 401 Unauthorized

• The webhook secret does not match. Regenerate using Reconfigure Webhook
• Ensure the secret is copied exactly (no trailing whitespace)
• Check that the correct project ID is in the webhook URL

Push to branch does not trigger deployment

• Verify a branch mapping exists: GET /api/projects/{projectId}/branch-mappings
• Check that the webhook is configured for push events
• View webhook delivery logs in your Git provider for errors
• Confirm the project has a connected repository

Deploy key rejected by Git provider

• Regenerate the deploy key: POST /api/projects/{projectId}/repository/regenerate-key
• Add the new key to your repository's deploy key settings
• Ensure the key has read access (write access is not needed)

GitHub App not showing repositories

• Check that the GitHub App is installed on the correct GitHub organization
• Verify repository permissions in the GitHub App settings
• Reinstall the GitHub App if repositories are missing

Deployment triggered but fails at clone step

• The deploy key may have been revoked or removed from the repository
• The repository may be private and the key lacks access
• Network connectivity issue between oCore server and Git provider
• Check the deployment step output for the specific Git error