How OpenProject and GitLab integration links code activity to work packages
The purpose of this integration is to show code activity on the work it belongs to. Teams plan work in OpenProject, but branches, commits, merge requests and pipelines live in self-hosted GitLab, so a project manager or reviewer looking at a work package sees a status that can lag behind the code. The goal is to have merge requests, pipelines, branches and commits appear on the work package itself, with GitLab sending events to OpenProject through webhooks. Before you scope the work, confirm the exact method in OpenProject's current integration documentation: the connector or configuration it uses, the reference syntax developers must write, and the OpenProject edition that includes the feature. Do not design around assumptions about any of these.
The reference syntax drives most of the day-to-day effort, so decide how your developers will use it before anything is configured. Check the documented format against how your teams already name branches, write commit messages and title merge requests. If the format depends on a work package identifier, decide who assigns identifiers, how they are shared with engineers, and what happens to branches created before the integration goes live. Consider whether you will enforce the convention through GitLab settings such as push rules or merge request templates, or rely on a written standard and review. Enforcement reduces unlinked activity, but it also adds friction that teams should accept in advance.
Plan the permissions on both sides. In GitLab, confirm which role the documentation requires to create or manage project webhooks, and identify every repository in scope, since each one needs its webhook configured. Use a dedicated service identity or a named owner group rather than a personal account, so the integration does not break when a developer changes roles or leaves. In OpenProject, confirm which administrative rights are needed to configure the connection and which project roles determine who can see linked activity on a work package. Store the webhook secret in your secrets manager, restrict who can read or rotate it, and record who approved each permission.
Test the path end to end on a non-production project before rollout. A useful test covers a branch created with a reference, a merge request opened and merged, a failing and a passing pipeline, and a commit pushed directly to a branch. Confirm that each event appears on the correct work package and nowhere else. Check how closed or deleted branches and merge requests are displayed, and what a user without access to a linked project sees. Because GitLab calls OpenProject, also confirm that the network path, firewall rules and certificate trust between the two systems work in your environment, including in segmented or offline networks where the endpoint must be reachable from inside the boundary.
After go-live, assign an owner for the integration. Webhook URLs, secrets and service identities change over time, and each change can silently stop events from arriving. GitLab ships a minor release each month and patch releases twice a month, and OpenProject publishes regular releases, so schedule a check of linked activity after each upgrade of either system. Add a periodic review of which repositories are connected, which identities hold webhook rights, and whether the reference convention is still followed. Ask your implementation partner or your own team to document these checks in the runbook before the first production change window.
What you need before connecting OpenProject to GitLab
Connecting OpenProject to GitLab depends on four things on different sides of the setup: the software versions, the accounts that authorize the link, the network path for webhooks and the trust between the two HTTPS endpoints. Check each one before you configure a webhook, because a gap in any of them usually shows up as events that never reach a work package.
Supported versions on both sides
Start with a supported OpenProject release and a maintained GitLab version. The supplied release notes list 17.9.0 and 17.9.2 as current OpenProject releases, and GitLab's maintenance policy names 19.5, 19.4 and 19.3 as the lines it currently maintains. Confirm the latest stable lines on the day you plan the work. GitLab requires upgrades to pass through upgrade stops such as 19.5 and 19.8, so record both versions in your change plan and retest the webhook after each upgrade.
GitLab tier and feature needs
GitLab is offered as Free, Premium or Ultimate, and all three tiers are available for self-managed installations. Decide the tier by the features your teams need, such as advanced CI/CD and priority support in Premium, or application security testing and compliance features in Ultimate. The GitLab pricing page lists Premium at 29 US dollars per user per month billed annually and shows Ultimate as custom priced, so request a written quote for the seats you need. Confirm with GitLab which features you plan to use alongside the OpenProject link.
GitLab service account with project rights
Decide which GitLab identity authorizes the connection. A dedicated service account keeps the link stable when staff change roles, while a personal user account ties the integration to one person's access and breaks if that person leaves. Grant the identity access only to the target projects and only at the role the integration needs. Check which token scopes your GitLab version requires before you store the credential in OpenProject, and record who owns its renewal.
OpenProject administrator account
Configuring the connection and the project mapping in OpenProject requires an administrator. Name one or two people who will hold this account, and enable multi-factor sign-in where your identity setup supports it. Confirm in the OpenProject administration documentation which settings need admin rights and which project managers can change them, because that decides who can alter webhook targets or credentials later.
Inbound network path to the webhook
GitLab sends event data to an OpenProject webhook endpoint, so traffic must flow from the GitLab server to the OpenProject host over HTTPS. Confirm that the GitLab host or its outbound proxy can reach the address and port your OpenProject instance serves, and that firewall, load balancer and reverse proxy rules allow the request. Test the route from the GitLab host itself, because a test from a workstation shows only that the endpoint is reachable from that workstation.
Certificate trust between the two systems
GitLab must trust the HTTPS certificate that OpenProject presents, or webhook deliveries fail during the TLS handshake. If your certificates come from an internal certificate authority, install the root and intermediate certificates on the GitLab host, then verify the chain with a command-line TLS check run from that host. Record the certificate expiry date and schedule renewal so that event delivery continues through the change window.
How webhooks carry GitLab events into OpenProject
The integration moves information in one direction at the moment of activity: GitLab sends a webhook payload to an OpenProject endpoint each time a configured event occurs, and OpenProject decides whether that event belongs to a work package. In sequence, a developer opens a merge request, pushes a commit or triggers a pipeline in a self-hosted GitLab project. GitLab builds an HTTP POST with a JSON body and sends it to the URL set in the project's webhook settings. OpenProject receives the payload, reads the text and identifier fields, searches them for a work package reference, and, if it finds a match, records the activity on that work package. Nothing is pulled from GitLab on a schedule, so a failed delivery leaves a gap in the work package history.
Reference matching is the first thing to confirm. Check the current OpenProject documentation and then test on a non-production instance whether references are matched by numeric work package ID, by project identifier prefix, or by both. Also confirm which fields are searched: the branch name, the commit message, the merge request title or the merge request description. Ask how a reference is handled when a commit message is amended after a push, and whether a second reference in the same title links the event to two work packages. Do not assume the OP# format used in the GitHub integration applies to GitLab. Build a test project with several work packages and a set of branches, commits and merge requests that use each candidate format, then record exactly what appears.
Event coverage also needs confirmation before anyone promises it to stakeholders. The scope for this integration names merge request, pipeline, push and commit events as the likely set, but the supported list and the data each event writes to a work package must come from the OpenProject documentation or from a vendor confirmation. For each supported event, record which fields are read, what appears on the work package (for example, a status, a link, an author or a timestamp), and whether a pipeline result is shown when a referenced branch runs CI. Find out whether the integration expects one webhook per GitLab project or can accept events from a group-level hook, and plan the GitLab configuration to match.
Because GitLab initiates every delivery, the OpenProject endpoint must be reachable from the GitLab server, and the GitLab server must trust the certificate that protects that endpoint. In an internal or air-gapped deployment, confirm the network path, the TLS trust chain, and whether any GitLab outbound request restriction blocks the OpenProject address. Confirm whether the OpenProject side verifies a shared secret or signature on each payload, where that secret is stored, and how it is rotated. Plan to review the recent delivery history for the webhook in GitLab after each test, since it shows failed responses that would otherwise go unnoticed. Finally, remember that commit titles and branch names from private repositories will appear on work packages, so confirm who can view those work packages before the integration goes live.
Configuration sequence for the GitLab webhook connection
This sequence connects a self-hosted GitLab instance to OpenProject so that merge requests, pipelines, branches and commits appear on the work packages they reference. Each step closes with a check you can see in one of the two systems, so faults surface before the next layer is added. Confirm exact menu paths and field names against the current OpenProject and GitLab documentation before you start.
Enable the integration and record the endpoint
An OpenProject administrator turns on the GitLab integration and notes the webhook endpoint it provides for your instance. Confirm the menu path and the setting name in the current OpenProject documentation, because labels can change between releases. Record the endpoint in your change record and check that it is reachable from the GitLab host, since GitLab must be able to send requests to it over your network. Done means the integration shows as enabled and the endpoint is documented for the steps that follow.
Create a scoped GitLab access token
A GitLab administrator or project owner creates the credential that OpenProject uses to read project data. Where your GitLab edition and access policy allow it, use a dedicated service account rather than a personal account. Confirm which scopes the OpenProject connector requires in its documentation, and grant only those. Store the token in your secrets manager, then check that a read request made with it succeeds against one test project before you continue.
Configure the webhook for chosen projects or groups
In GitLab, a project maintainer or group owner adds a webhook that points to the OpenProject endpoint, selects only the events the integration documents, and sets a secret token. Decide between project-level and group-level hooks based on your access model, since a group-level hook applies to every project beneath that group. Confirm the event names and the secret token field label in GitLab's current webhook documentation. Done means the webhook is listed as active and a test delivery shows a successful response in the webhook log.
Reference a test work package in a branch
A developer creates a test branch in a non-production project and cites the test work package in the branch name or commit message, using the reference format the integration documents. The developer then opens a merge request whose description cites the same work package. Using a non-production project keeps test activity out of live planning. Confirm the reference format in the OpenProject documentation before you start. Done means the merge request exists in GitLab and the test work package is identified for both teams.
Check the delivery log and work package activity
In GitLab, open the webhook's recent deliveries and confirm that each test event returned a success response. In OpenProject, open the test work package and look for activity from the branch, merge request and pipeline events. If a delivery succeeded but no activity appears, check the work package reference and the project mapping before you change the webhook. Done means each test event is visible on the work package and its matching delivery is recorded as successful in GitLab.
Record the configuration and test evidence
Save the endpoint, token scope, webhook events, project or group scope and test results in your change record, then remove the test branch once the evidence is captured. Ask your security team to review how the secret token is stored and what access the service account holds. Confirm your retention and backup expectations for this configuration against your own policy. Done means the change record shows each check passed and names the owners of the token and the webhook.
How GitLab objects map to OpenProject work packages
This table shows how each GitLab object is matched to an OpenProject work package or the field it updates. Read the middle column for the target and the last column for the matching rule. Where the documentation does not settle a rule, the cell names the question to test in a non-production OpenProject instance before go-live.
| GitLab object | OpenProject counterpart or field | Matching rule and what to verify |
|---|---|---|
| Project | OpenProject project that receives the webhook events | Set up per OpenProject project through the webhook configuration. Verify whether one GitLab project can feed more than one OpenProject project. |
| Branch | Activity entry on the referenced work package | Matched by work package ID in the branch name (to be confirmed). Verify whether branch names are read at all and which event types they produce. |
| Commit | Activity entry on the referenced work package | Matched by work package ID in the commit message (to be confirmed). Verify whether every commit is sent or only commits from pushes that match a reference. |
| Merge request | Linked work package, with activity and status updates | Matched by work package ID in the title or description (to be confirmed). Verify which merge request events change work package fields, such as status. |
| Pipeline | Pipeline result shown as activity on the linked work package | Matched through the linked merge request or commit (to be confirmed). Verify which pipeline events are sent and how they appear on the work package. |
| User | Author of the activity, matched to an OpenProject account | Matched by email address or login (to be confirmed). Verify what happens when no OpenProject account exists, since the activity may lose attribution. |
Permissions and hardening for the GitLab and OpenProject link
The GitLab and OpenProject link moves project activity between two systems, so its permissions and transport settings need the same care as the systems themselves. The cards cover the GitLab identity the link uses, how webhook deliveries are authenticated and encrypted, what OpenProject membership exposes, and how logs and patches stay current on both sides.
Least-privilege GitLab access
Create a dedicated service account or project access token for the link, and keep administrator personal tokens out of it. Grant only the scopes and project roles that the webhook and read calls need, limit the token to the projects that feed OpenProject, and set expiry dates. Check GitLab's authentication and authorization documentation and its hardening recommendations for current token types and defaults before you finalize the role.
Webhook secret tokens
Set a secret token on every webhook that sends GitLab events to OpenProject, and configure the receiving side to reject any delivery whose token does not match the expected value. Store the value in a secrets manager and limit who can read it. Rotate it on a schedule and after any staff change, then send a deliberately wrong token in testing to confirm it is refused.
TLS verification on both ends
Keep SSL verification enabled on the GitLab webhook so it validates the OpenProject certificate, and confirm that the certificate chain includes any internal certificate authority your GitLab instance trusts. Confirm that OpenProject serves the webhook endpoint only over HTTPS. Turning verification off to get a test working is a common shortcut, so catch it in change review before go-live.
OpenProject membership limits updates
The projects and work packages that show GitLab activity depend on what the integration user can see in OpenProject, so membership and roles decide what appears on each work package. Add the integration user only to the projects that should receive GitLab activity. Test with a private project and a restricted work package to confirm that a user without access sees nothing from it, and confirm how your OpenProject version applies this rule.
Log review on both sides
Review GitLab audit events for changes to tokens, webhooks and project membership, and check webhook delivery history for failed or unexpected calls. On the OpenProject side, review application and access logs for requests from the GitLab endpoint and for administrative changes to the integration user. Agree who reviews each log, how often, and how a finding reaches your security team.
Patch both sides on time
GitLab backports security fixes to the previous two monthly releases, but bug fixes go only to the current stable release. An instance that falls outside that security window may not receive fixes for issues that matter to the link, and a bug that affects webhooks will require moving to the current stable release. Read the GitLab maintenance policy, schedule a monthly review for GitLab and OpenProject, and track OpenProject release notes so both sides move together.
How to test the GitLab link before it goes live
Test the GitLab link in a non-production pair of OpenProject and self-managed GitLab before any team depends on it. Start by agreeing acceptance criteria with the client in writing, because test results only mean something when both sides have signed off on the expected behavior. The criteria should name the events that must appear on a work package (branches, merge requests, pipeline status and commits), the roles that must see them, and what the team does when a link fails. Once those are agreed, build the test environment with the same OpenProject and GitLab versions planned for production. The GitLab maintenance policy backports bug fixes only to the current stable release, so a test environment on a different version can pass on a fix that production will not yet receive.
Create a test project in OpenProject and a test work package, then record its numeric ID before anything else happens. In the linked GitLab test project, create a branch and commit message that use the work package reference format the integration expects. Confirm that format in the integration documentation for your versions, because the exact syntax is the first thing a tester will check and the easiest thing to get wrong. Open a merge request that references the same work package, then run a pipeline on that branch. After each step, check the work package activity for the expected entries: the branch, the merge request state, the pipeline result and the commit list. Record what appears, whether the entries are complete, and how long they take to show. Repeat the sequence once to confirm the second run behaves the same way as the first.
Then test the cases most likely to fail in production. A wrong reference, such as an ID that does not exist or one that belongs to another project, should not attach activity to the wrong work package, and it should leave a trace the team can find. Test a user who has a GitLab account but no membership in the OpenProject project. That user must not see work package details through the link, and the team should confirm which GitLab information, if any, is sent back to OpenProject for that user. Next, delete a branch after a merge request has referenced it, and check what the work package shows and whether the merge request history survives. Finally, interrupt delivery. Take OpenProject or the network path offline, generate branch and pipeline events in GitLab, restore service, and check the webhook delivery log for retries, duplicate entries and event order. Confirm the expected retry behavior in the vendor documentation for your versions.
Record evidence for every test: a screenshot or export of the work package, the GitLab webhook delivery entry, the OpenProject account used for the test, and the pass or fail result against the agreed criterion. Failed cases go back into the configuration or the build for a retest rather than being noted in a report and left open. Decide before testing starts who may accept a failed criterion as a known limitation, and write that decision into the plan. Keep the plan so it can be rerun after each OpenProject or GitLab upgrade, since either release can change how events are sent or parsed. Ask the implementation team to confirm which events and failure behaviors are in scope for your specific versions before the first test run.
Common GitLab to OpenProject webhook failures and fixes
This table lists common failures between self-hosted GitLab and OpenProject webhooks, with the probable cause, the check to run and the fix for each. Causes marked as verify in the target environment are not confirmed in documentation, so test them against your own versions and configuration. Start with delivery responses, because many symptoms trace back to a failed delivery or an identity mismatch.
| Symptom | Probable cause | Check to run | Fix |
|---|---|---|---|
| Deliveries return HTTP errors | OpenProject endpoint unreachable from GitLab, or a proxy or firewall blocks the request (verify in target environment) | Open the webhook's recent deliveries in GitLab and read the response code and body for each failure | Confirm network routes and reverse proxy rules from the GitLab host, then resend the failed delivery |
| Activity does not appear on a work package | Branch, commit or merge request text lacks a valid work package reference, or the format differs from the one expected (verify in target environment) | Compare the reference in the commit, branch or title with the work package ID and the documented format | Use the documented reference format in new branches, commits or titles, then push a test event |
| Activity attributed to the wrong user | The GitLab commit author email does not match an OpenProject account, or the accounts are not linked (verify in target environment) | Compare the commit author email with the email on the OpenProject user and check the linked identity | Align the email addresses or link the accounts, then confirm with a test commit |
| Events missing after a GitLab upgrade | Webhook trigger settings changed, or the payload or event types changed in the new version (verify in target environment) | Review the hook's trigger list against the events you expect and read the notes for the target GitLab version | Re-enable the required trigger types, then run a test push and a test merge request |
| Certificate errors on a private CA | GitLab does not trust the internal CA that signed the OpenProject certificate (verify which trust store applies in your setup) | Read the TLS error in the delivery details and test the certificate chain from the GitLab host with the CA file | Add the root and intermediate CA certificates for GitLab's custom CA setup, reconfigure GitLab, then redeliver |
| Duplicate activity entries | Retried deliveries processed twice, or more than one hook points at the same endpoint (verify in target environment) | List webhooks at project and group level and look for duplicate URLs or triggers | Remove the duplicate hooks so each scope sends events to one endpoint |
| Updates rejected with permission errors | The account that receives events lacks a role on the project that allows the update (verify in target environment) | Check the integration account's project role and the expected permissions for the activity type | Grant the minimum project role needed, then repeat a test event |
What buyers ask about GitLab and OpenProject integration cost, effort and ownership
What drives the cost of a GitLab and OpenProject integration?
Scope is the main driver: how many OpenProject projects and GitLab groups and projects need links, which GitLab events (merge requests, pipelines, branches and commits) should appear on which work packages, and how those mapping rules are defined. Identity mapping is often the largest unknown, because GitLab users whose emails or usernames do not match OpenProject accounts need manual decisions. The GitLab tier and hosting model also matter. GitLab's pricing page lists Premium at 29 US dollars per user per month billed annually, and that licence is bought separately from the integration work. Testing depth adds effort in proportion to the number of flows you verify. Ask any quote to itemize discovery, mapping design, build, testing, handover and documentation, and to state which items are one-time and which recur.
Can our own team build the GitLab and OpenProject integration alone?
Yes, if your team has administrator skills in both GitLab and OpenProject, a test instance of each, and time to own the webhook configuration and mapping rules. Your GitLab administrators need the rights to create project or group webhooks, and your OpenProject administrators need to confirm which edition and settings the integration requires, which you should verify in the OpenProject documentation before you start. Teams most often run into trouble with identity mapping and with testing every event type across merge requests, pipelines and branches. A partner is worth considering when internal staff are stretched, when no one owns upgrades on both platforms, or when the mapping rules are still under debate across several teams.
How long does a GitLab and OpenProject integration take to deliver?
Duration depends on scope, and DeployOpen sets it in a written plan agreed before work starts. The main inputs are the number of projects and groups in scope, how complex the mapping rules are, how much identity mapping must be resolved, how deep the testing goes, and how quickly your reviewers and test instances are available. Waiting on access approvals or sign-off decisions often takes longer than the technical build. Ask for the plan to show milestones for discovery and mapping design, build in a test environment, verification against your sign-off criteria, cutover to production and handover. Most engagements are fixed-scope, so the timeline should be tied to the deliverables listed in the agreed scope.
What do we need to provide for a GitLab and OpenProject integration project?
Plan to provide administrator access to GitLab and OpenProject in both test and production, along with a test instance of each so changes never reach live projects first. You will also need representative test projects and groups, named reviewers who can confirm results, and a written set of sign-off criteria covering which events must appear on which work packages. Network paths between GitLab and OpenProject must allow webhook delivery, and your security team should review the credentials and secrets used. Decisions on mapping rules and identity matching should be made before the build starts, since changing them later usually means rework. Confirm each item in the written scope so that delays are visible early.
What recurring work does a GitLab and OpenProject integration create?
The main recurring work is upgrades on both sides. According to GitLab's maintenance policy, GitLab ships a minor release on the third Thursday of each month and patch releases twice a month, and bug fixes are backported only to the current stable release. GitLab's upgrade paths documentation also requires upgrade stops at versions x.2, x.5, x.8 and x.11, such as 18.2, 18.5, 18.8 and 18.11, so you cannot skip them. OpenProject ships point releases as well, for example 17.9.2 on October 15, 2026, according to the OpenProject release notes. After each upgrade, retest the webhook flows, because payloads and API behavior can change. Ongoing support, upgrades and continuous testing are available from DeployOpen as retainers.
Does the integration still work when GitLab runs in an air-gapped network?
It can, but you need to confirm the design before committing to it. GitLab documents running self-managed instances in offline, air-gapped environments, according to its offline environments page. The integration depends on webhook delivery from GitLab to OpenProject, so the network route between the two must stay inside your environment, and the webhook must not depend on outbound internet access. Check the OpenProject side too, including how it receives requests, how certificates are issued and trusted, and whether any feature you need depends on an external service. Test the flows in a network that matches production, not a lab with open routing, because firewall and proxy rules are a common cause of failed deliveries.
What usually breaks in GitLab to OpenProject webhook links?
The most common failures are identity mismatches, where a GitLab author cannot be matched to an OpenProject user, and expired or rotated secrets that cause deliveries to be rejected. TLS certificate problems and firewall or proxy rules that block requests are the next most frequent. Check whether GitLab disables or retries webhooks after repeated failures, since the behavior determines how quickly you notice a problem, and confirm the current behavior in GitLab's documentation for your version. Upgrades can also change event payloads. For monitoring, review the webhook delivery history in GitLab and the OpenProject application logs after each change. Self-managed GitLab deployments for 3,000 or more users are generally planned with high availability, which affects where webhook traffic is handled, so review that design early.
How DeployOpen scopes and delivers the GitLab and OpenProject integration
DeployOpen scopes the OpenProject and GitLab integration in a written, fixed-scope engagement, then builds the webhook connection inside infrastructure you control. Each stage produces documented decisions and handover material that your team keeps after delivery. Ongoing support is available as a retainer once the integration is live.
How we scope
- The written scope names the OpenProject projects, GitLab groups and repositories in each integration.
- It states which events flow from GitLab, such as merge requests, pipelines, branches and commits.
- It records the service account permissions both systems need, agreed with your identity and security owners.
How we build
- Build the GitLab webhook configuration and OpenProject receiving side inside your self-hosted environments.
- Define how branch names and commit messages reference OpenProject work packages, and test each reference format.
- Test each event type in a staging instance before any change reaches your production OpenProject.
How we hand over
- Handover includes configuration records, an event and permission map, and runbooks for your administrators.
- Documentation covers webhook secret storage, rotation steps and every account the integration uses.
- Knowledge transfer sessions cover troubleshooting failed webhook deliveries and reviewing permission changes.
How we support
- Ongoing support is available as a retainer covering OpenProject and GitLab upgrades that affect the integration.
- GitLab release cadence and upgrade stops mean webhook behavior should be rechecked after each planned upgrade.
- Re-test the event map after OpenProject releases, and confirm the integration against the current release notes.
