Set Up CI/CD with GitHub
Connect a GitHub repository and configure automatic deployments on push with branch-to-environment mapping.
This tutorial shows you how to connect a GitHub repository to oCore and set up automatic deployments. When you push code to a branch, oCore will automatically deploy the changes to the corresponding environment.
Estimated time: 20 minutes
This tutorial assumes you already have a project with at least one environment. If not, complete the Deploy Your First Odoo Instance tutorial first.
What you will build
- A GitHub integration with webhook-based deployment triggers
- Branch-to-environment mapping so each branch deploys to the correct environment
- Automatic deployments triggered by
git push
How oCore CI/CD works
When properly configured, the deployment flow works as follows:
Step 1: Connect your GitHub account
Navigate to your organization's Settings page and select the Git Integration tab.
Click Connect GitHub. You will be redirected to GitHub to authorize the oCore integration.
On GitHub, review the permissions requested:
- Repository access: Read access to code and metadata
- Webhooks: Create and manage webhooks for push events
- Commit statuses: Update deployment status on commits
Select the repositories you want to make available to oCore. You can choose specific repositories or grant access to all repositories in the organization.
Click Install & Authorize to complete the connection.
Git Integration settings
Configure your GitHub connection in organization settings.
Step 2: Configure the webhook
Once GitHub is connected, oCore automatically sets up a webhook on your repository. Verify the webhook is active:
In your GitHub repository, go to Settings > Webhooks.
You should see a webhook pointing to your oCore instance (e.g., https://ocore.example.com/api/webhooks/github/{projectId}).
Verify the webhook is configured to trigger on Push events.
The webhook should show a green checkmark indicating a successful recent delivery. If it shows an error, check that your oCore instance is publicly accessible at the configured URL.
If your oCore instance is behind a firewall or VPN, GitHub webhooks will not be able to reach it. You will need to either expose the webhook endpoint publicly or set up a webhook relay service.
Step 3: Configure branch-to-environment mapping
Branch mapping tells oCore which environment to deploy when changes are pushed to a specific branch.
Navigate to your project in oCore and open the Settings tab.
Under Branch Mapping, configure which branches map to which environments:
| Branch | Environment | Auto-deploy |
|---|---|---|
main | Production | Yes |
staging | Staging | Yes |
develop | Development | Yes |
For each mapping, choose whether auto-deploy is enabled. When enabled, every push to that branch triggers an automatic deployment. When disabled, deployments must be triggered manually from the dashboard.
Click Save to apply the branch mapping.
Project settings
Navigate to your project to configure branch mapping.
You can map multiple branches to different environments. A common pattern is main for production, staging for pre-release testing, and develop for active development.
Step 4: Push a commit and watch automatic deployment
Test the CI/CD pipeline by pushing a change to your mapped branch:
Make a change in your Odoo addon code. For example, update a module's version in __manifest__.py:
{
'name': 'My Module',
'version': '17.0.1.0.1', # Bump version
# ...
}Commit and push the change:
git add .
git commit -m "chore: bump module version"
git push origin mainOpen the oCore dashboard. Navigate to your environment's Deployments tab. You should see a new deployment being created automatically within a few seconds.
Watch the deployment progress through its stages:
- Queued -- Deployment job is created
- Building -- Pulling latest code from the repository
- Deploying -- Restarting the Odoo instance with updated code
- Success -- Deployment completed successfully
Step 5: Monitor deployment status
oCore provides several ways to monitor your deployments:
In the dashboard
View deployments
Navigate to your environment's Deployments tab to monitor deployment history.
The deployment list shows:
- Status: Success, Failed, or In Progress
- Trigger: Whether the deployment was triggered by a webhook, manual action, or schedule
- Commit: The Git commit SHA and message that triggered the deployment
- Duration: How long the deployment took
- Timestamp: When the deployment started and finished
On GitHub
oCore updates the commit status on GitHub, so you can see deployment results directly in your pull requests and commit history:
- A green checkmark means the deployment succeeded
- A red X means the deployment failed (click it to see details in oCore)
- A yellow dot means the deployment is in progress
Deployment notifications
Configure notifications in your organization settings to receive alerts about deployment outcomes via email or webhook.
Troubleshooting
Webhook not triggering
If pushing to GitHub does not create a deployment:
- Check the webhook delivery history in GitHub (Settings > Webhooks > Recent Deliveries)
- Verify the webhook URL matches your oCore instance's public URL
- Ensure the branch is mapped to an environment with auto-deploy enabled
- Check oCore's activity log for any webhook processing errors
Deployment fails
If the deployment is created but fails:
- Check the deployment logs in oCore for error details
- Common issues include:
- Python dependency installation failures
- Odoo module syntax errors
- Database migration errors
- Fix the issue in your code, push again, and oCore will deploy the fix automatically
Branch not matched
If pushes to a branch do not trigger deployments:
- Verify the branch name in your mapping matches exactly (case-sensitive)
- Check that the environment linked to the branch is active and not paused
- Confirm auto-deploy is enabled for that branch mapping
What to do next
- Set up a staging environment to test changes before production
- Configure deployment approvals for production environments requiring manual approval
- Add more repositories to your oCore projects for multi-repo setups
- Implement a backup strategy before deploying to production. See Implement a Backup Strategy.