How to connect GitHub pull requests and Actions to OpenProject work packages
The GitHub link ties pull requests and Actions status to OpenProject work packages through OP# references and webhooks, and it is available in the free Community edition. It addresses a common gap: developers work in GitHub, where branches, reviews and builds happen, while planners track scope, dates and ownership in OpenProject. Without a connection, the two records drift apart, and a work package can still say "in progress" long after its code has merged or its pipeline has started failing. The link is meant to keep both views aligned without asking developers to update OpenProject by hand.
On the work package itself, the integration shows linked pull requests and the status of related Actions runs, so a planner or product owner can see whether implementation is under review, merged or failing checks. Developers get the planning context for a change in the same place, typically including the work package's status, owner and due date. Project managers and portfolio owners use the same record when they report progress, so the status they quote matches what the code is doing. Exactly which fields, activity entries and status details appear depends on the release in use, so confirm the displayed items in the current OpenProject documentation before you scope the build.
Several decisions come before any configuration. Decide which GitHub repositories should feed which OpenProject projects, because one repository may serve several teams and one team may use several repositories. Agree on the reference convention early: developers need to know where to place an OP# reference, such as in a branch name, pull request title or commit message, and planners need to know that a missing reference means the change will not appear on a work package. Also decide how the GitHub side authenticates, which account or app holds the access, and what it is allowed to read and write. Finally, confirm that your OpenProject server can receive webhook calls from GitHub, which may require a network rule or reverse proxy change on infrastructure you control.
Before build, confirm three things against the current OpenProject documentation for the release you run: the exact reference syntax the integration accepts, the GitHub event types it subscribes to, and the minimum permissions the GitHub side needs. Then test the path end to end in a non-production instance using a sample repository. Open a pull request, run a deliberately failing Actions workflow, then merge, and check what appears on the work package at each step. Treat that test as the acceptance record for the planning team, since it shows what they will and will not see. Keep the test notes with your change records so the setup can be repeated after an upgrade.
What you need before you configure the GitHub link
Six items need to be in place before you open the GitHub settings in OpenProject. Each one either lets OpenProject accept requests from GitHub or lets you test the link without touching production repositories. Check them in this order so that any failure is easy to trace.
Running OpenProject on a supported release
Your self-hosted OpenProject instance must run a release that the current documentation supports. This page uses the 17.x release line as its reference, and OpenProject 17.9.2 was released on October 15, 2026. Check your installed version in the administration area, then compare it with the OpenProject release notes before you configure anything, since the GitHub integration settings can change between releases.
An administrator account in OpenProject
Linking a repository changes project-level integration settings and stores GitHub credentials, so the person doing the configuration needs administrator rights in OpenProject. Confirm the account can open the administration area and can see every project where work packages will receive GitHub activity. Use a named administrator account so the audit trail shows who saved the credentials and who changed the settings later.
GitHub owner rights to create credentials
Someone with owner rights on the GitHub organization, or administrative rights on the repository owner, must create the credential that OpenProject uses to read repository activity. The credential type, whether a token or an app, and its scopes depend on the authentication method described in the current OpenProject GitHub integration documentation. Confirm that method and those scopes before creating anything, and agree who holds the credential and how it will be rotated.
A reachable HTTPS endpoint for webhooks
GitHub delivers events to OpenProject by sending HTTP requests to a public address, so the OpenProject server needs an HTTPS URL that GitHub can reach. Confirm the hostname, port and certificate chain with your network team, and make sure GitHub can validate the certificate. A plain HTTP address or an untrusted certificate can cause deliveries to fail, so send a test delivery before you rely on the link.
A reverse proxy or firewall rule for internal servers
If OpenProject runs on a private network, GitHub cannot reach it until a reverse proxy or firewall rule forwards inbound requests to the application. Limit the rule to the webhook path where your controls allow, and keep the OpenProject server itself off the open internet. Record the rule and its owner, so that a later firewall change does not silently break the link.
The Community edition and a test repository
The free Community edition is the licensing point for this integration, so you do not need a paid OpenProject plan to configure the link. Check the plan requirement in the current documentation before you buy anything. Use a test repository with a few pull requests and one workflow run, separate from production code, to confirm references and status updates before you widen the scope.
How OP# references and webhooks move status between the two systems
Status moves in one direction for most events. A developer writes an OP# work package reference in a branch name, commit message, pull request title or pull request description. GitHub then sends event notifications to OpenProject through a webhook, and OpenProject looks for the reference in the payload. When it finds a match, it attaches the pull request or Actions result to the referenced work package, so the project team sees development activity where it plans the work. The developer does not need to edit the work package to make this happen, but the reference has to be present and written in one of the agreed places.
The main trade-off is between event-driven updates and manual linking. Event-driven updates keep work packages current without extra clicks and reduce the drift that builds up when people forget to update a ticket. They also depend on three things working at once: the webhook is configured correctly, GitHub can reach the OpenProject instance, and the developer wrote the reference correctly. Manual linking is explicit and can cover work that has no reference, but it relies on people remembering and produces stale status. For most teams the practical decision is which convention is mandatory, which work may proceed without a reference, and who reviews gaps before a sprint review.
Only references in the agreed places get picked up. If the team agrees that pull request titles and branch names carry the reference, a commit message on an untracked branch or a note in a review comment may never reach the work package. Write the list of accepted locations into the team's contribution guide and test each one in a sandbox repository before rollout. Also confirm how the current release handles several references in one place, whether the match is case sensitive, and which separators and number formats it accepts. The supplied facts do not describe reference parsing rules, so confirm these with the OpenProject integration documentation for your version.
Confirm which GitHub events the current release handles before you promise any status behavior. Typical candidates include pull request opened, updated, closed and merged, plus push events and completed Actions workflow runs, but the supported list is not part of the supplied facts. For each event, check which status fields change, whether a closed work package still receives updates, and how the webhook secret is verified. Plan for missed deliveries by reviewing GitHub's webhook delivery log during the pilot and by agreeing on a periodic manual check of open pull requests against open work packages. Record the answers in the design document so the team knows what the integration will and will not show.
Configuration sequence for the GitHub link
This sequence connects a GitHub repository to OpenProject so that OP# references in branches and pull requests appear on work packages. Each step closes with a check you can run before moving on, so a failure traces back to one configuration point. The setup works in the free Community edition, and it assumes you control both the OpenProject host and the repository settings.
Confirm OpenProject is reachable from GitHub
Confirm that the OpenProject base URL resolves and accepts HTTPS requests from outside your internal network, because GitHub sends webhook deliveries from its own servers. A URL that works only on the office network will fail without an obvious error at this point. Check that the certificate is valid, trusted and not missing intermediate certificates. Ask your network team whether a firewall or reverse proxy restricts inbound requests to the webhook path. Done when an external HTTPS request to the base URL returns a valid certificate and a normal response.
Create the GitHub credential with minimum scopes
Create the credential OpenProject will use to read GitHub data, limited to the scopes the official OpenProject documentation names for this integration. Confirm the scope names in the current documentation before you create anything, because requirements can change between releases. Prefer a credential owned by a dedicated service account or an organization GitHub App, so access survives staff changes. Record where the credential is stored and limit who can view it. Done when the credential exists, lists only the documented scopes, and a test call confirms it can read the target repository.
Enable the integration and enter the credential
An OpenProject administrator enables the GitHub integration in the administration area and enters the credential from the previous step. Store the credential only in OpenProject's secure settings, and keep it out of configuration files and shared documents. Menu labels change between releases, so find the integration settings through the administration guide for your installed version. Done when OpenProject saves the settings without error, the integration shows as active, and any connection test available in your version reports success.
Register the webhook with endpoint and secret
On the GitHub repository, add a webhook that points to the OpenProject endpoint named in the integration documentation. Generate a long random secret with a password manager or cryptographic generator, enter it in the webhook, and enter the same value in OpenProject. Keep the secret in your secrets management system. Select only the event types you plan to use now, and adjust them in the next step. Done when GitHub's webhook page shows a successful delivery for a test ping sent from the webhook settings.
Enable the Actions and pull request events
Subscribe to the pull request and workflow run events the team needs for status on work packages, and confirm the exact event names in the documentation for your OpenProject version. Keep the list short so unrelated repository activity does not clutter work packages. Open a pull request and run a workflow on a test branch so that real events are generated. Done when each subscribed event appears in the GitHub delivery log with a success response and matching entries appear in the OpenProject delivery or log view.
Test the link with an OP# branch and pull request
Create a branch in a test repository whose name or commit message includes an OP# reference to an existing work package in a test project. Open a pull request that carries the same reference, and let the Actions workflow finish. Confirm the reference format the documentation accepts, because the parser may expect a specific pattern. Open the test work package and check that the branch, pull request and workflow status are listed. Done when all three links are visible on the work package and the delivery log shows no errors. Remove the test items once the check passes.
Which GitHub objects map to which OpenProject fields
This table pairs each GitHub object with the OpenProject object or field it updates, and names the decision the team must settle before build. User matching depends on the identities that already exist in OpenProject, so confirm the current release's mapping rules for usernames, emails and project links before you finalize the design.
| GitHub object | OpenProject field | Decision for the team |
|---|---|---|
| Repository | Project | Which OpenProject project receives events when several projects share one repository, and whether the link is set by repository name or by a project identifier. |
| Branch | Work package reference in the branch name | Whether teams put the OP# reference in branch names, and whether the integration reads branch names at all or only titles and messages. |
| Pull request | Work package, linked through an OP# reference in the title or description | Whether a pull request without a reference is ignored or flagged, and whether one pull request may reference more than one work package. |
| Commit | Work package reference in the commit message | Whether every commit must carry the reference, who enforces the format, and whether only the subject line or the full message is parsed. |
| Actions workflow run | Status or activity on the linked work package | Which workflows post status, and whether a failed run changes the work package status or only adds an activity entry. |
| Pull request author | User account matched to the work package activity | How GitHub logins match OpenProject accounts, whether by username or verified email, and what happens to contractors who have no account. |
| Pull request reviewer | User account as assignee or watcher | Whether reviewers are added as watchers or assignees, and how unmatched reviewers are handled so they do not block the work package. |
| Pull request state (open, merged, closed) | Work package status | Which OpenProject status each GitHub state maps to, since status names are set per installation and per workflow. |
Securing the webhook and the GitHub credential
These settings decide who can send data into OpenProject, what the GitHub credential can reach, and what happens when a delivery fails. Each one sits on the path between a public GitHub event and an internal work package, so a gap in any single control weakens the link. Confirm every setting against the OpenProject administration guide for your release before go-live.
Verify the webhook secret
Configure a shared secret on the GitHub webhook and confirm that OpenProject checks the signature on every delivery before it changes a work package. Requests that fail the check should be rejected and logged. Generate the secret with a cryptographically strong random generator and store it in your secrets manager. Confirm in the OpenProject administration guide which signature header and method your release expects, then test with a deliberately wrong secret before go-live.
Protect the public endpoint
The webhook receiver must be reachable from GitHub, so it is exposed to the internet. Serve it only over TLS with a certificate your team manages and renews, and disable plain HTTP on that path. Add rate limiting at the reverse proxy or load balancer. Where your network team can support it, restrict inbound traffic to the IP ranges GitHub publishes for webhook delivery, and confirm how those ranges apply to your setup. Check each control against the OpenProject administration guide.
Scope and rotate the GitHub credential
The credential OpenProject uses to read GitHub should reach only the repositories in scope. Choose a credential type that can be restricted per repository and grant only the read permissions the link needs, so a leak exposes as little code as possible. Record an owner, the date of issue and the revocation steps, and rotate the credential on the schedule your security policy sets. Confirm in the OpenProject administration guide how a rotated value is updated without breaking existing links.
Grant link roles by least privilege
Only a small group of OpenProject users should be able to create or edit links between repositories and work packages, because each link decides which GitHub activity appears on internal records. Assign a dedicated role for managing integration settings, and give it only to named people who need it. Review that role's project and global permissions in the OpenProject administration guide, since both may affect who can change integration configuration. Remove the role when people change teams.
Log deliveries and failed signatures
Keep a record of each webhook delivery, including its time, event type, result and the work package it changed. Alert on repeated signature failures and processing errors. Forward these entries to your central logging platform so an investigation does not depend on a single application host. Check the OpenProject administration guide for where delivery history is stored and how long it is kept, and set retention to match your policy. Make sure the secret and the credential never appear in any log line.
Decide what public text may appear
Anyone can read a public repository, and once a link exists, pull request titles, branch names and commit messages from that repository can appear on an internal work package. Decide with the project owners which fields may flow through, and whether the integration should link only repositories that contain no internal detail. Review who can comment on those pull requests, since their text may reach internal records. Write the decision into the integration runbook.
How to test the link before the team relies on it
Run this test plan in a sandbox before any delivery team depends on the link. Create a sandbox project in OpenProject with a small number of work packages, and note the ID of each one, because the OP# references in the tests depend on those numbers. Create a separate test repository in GitHub that no delivery work uses, and connect the integration to it with a test account. Record the OpenProject version, the GitHub organization and the start date of the run before the first case. A separate sandbox keeps failed tests away from live work packages and makes the evidence easier to read later.
The first three cases check how the integration reads references. Open a pull request whose title or description contains a valid OP# reference to a work package in the sandbox project, and expect the pull request to appear on that work package with its title, state and author. Then open a second pull request that refers to a work package ID that does not exist, and a third pull request with no reference at all. Expect neither to attach to any work package in the sandbox, and expect no unintended change to the work packages that do exist. Confirm in your version's documentation which part of the pull request the integration reads, and test that part specifically, because a reference in the wrong place will look like a fault when it is really a configuration question.
Next, run two GitHub Actions workflows on a pull request that carries a valid reference: one that succeeds and one that fails on purpose. Expect the work package to show the status of each run, and expect the failed run to be distinguishable from the successful one without opening GitHub. Record the workflow name, run identifier, conclusion and the time the status appeared on the work package. If a status does not appear, check the delivery log in GitHub before changing OpenProject settings. A delivery that failed on the GitHub side has a different cause than one that reached OpenProject and was rejected, so record which of the two happened.
Close the pull request, confirm that the work package reflects the closed state, then reopen it and confirm that the state updates again. Finally, open the webhook's recent deliveries in GitHub, choose the reopen event and redeliver it. Expect the work package to stay in the same state, with no duplicate pull request entry and no second copy of the workflow status. Record the delivery identifier and the response code that OpenProject returned. If redelivery creates a duplicate, treat that as a finding to resolve before go-live, and confirm with the vendor how the integration handles repeated events in the version you run.
Keep the completed results as evidence for change management. For each case, record the input, the expected result, the observed result, the date, the OpenProject and GitHub versions in use, the tester, and a screenshot or exported log. Store the record with the change request so that a reviewer can trace the link's behavior back to a specific configuration. Repeat the full plan after every OpenProject upgrade, because the integration's behavior can change between releases. Repeat it after every GitHub credential rotation as well, since a rotated token or app key can stop deliveries in a way that is easy to miss until someone notices missing statuses.
Why GitHub activity does not appear on work packages
This table lists the most common reasons GitHub pull requests, branches or Actions status fail to show on OpenProject work packages. Each row gives the first check to run, usually in GitHub's webhook delivery history or the OpenProject server logs, followed by the fix. Start with the delivery log, because it shows whether GitHub sent the event and how OpenProject responded.
| Failure | Check first | Fix |
|---|---|---|
| Webhook not delivered | Open the webhook's Recent Deliveries in GitHub. Look for timeouts or no entries. | Confirm the OpenProject URL is reachable from the internet over HTTPS. Open the firewall or reverse proxy path for GitHub's delivery traffic. |
| Signature verification fails | Check the delivery response in GitHub for a rejection code, then the OpenProject log for signature errors. | Set the same webhook secret in GitHub and in OpenProject. Update both sides together after any rotation. |
| Credential lacks repository scope | Check the token or app installation for the affected repository and the permissions it grants. | Grant the missing repository access and read permissions. Confirm the exact list in the integration's setup documentation. |
| OP# reference missing or malformed | Compare the branch name, PR title and description with the exact OP# format the integration expects. | Rename the branch or edit the PR title to include the correct OP# and work package ID. Check the ID exists. |
| Work package in an uncovered project | Confirm the work package's project is inside the integration's configured project scope. | Add the project to the integration scope, or move the reference to a work package in an included project. |
| User identity not matched | Compare the GitHub account email with the OpenProject user's email, and check the activity author shown in GitHub. | Align the email addresses or link the accounts as the integration requires. Ask the user to reconnect if prompted. |
| Duplicate or stale entries after a URL change | Check GitHub for an old webhook still pointing at the previous address, and review recent deliveries for both URLs. | Remove the old webhook, update the payload URL, and clean up earlier entries as the documentation describes. Test with one new pull request. |
Questions buyers ask before they set up the GitHub link
Does the OpenProject GitHub link require an Enterprise plan?
The GitHub link is documented as available in the free Community edition, so it does not require an Enterprise plan. Confirm this against the current feature list on the OpenProject pricing page before you commit, because edition placement can change between releases. The Community edition is free and includes work packages, Gantt charts, agile boards, time tracking and dashboards, with community support. Enterprise on-premises licensing is priced per named user per month, with Basic at 5.95 euros and Professional at 10.95 euros (25-user minimum), Premium at 15.95 euros (100-user minimum), and Corporate on request for 250 or more users, according to the OpenProject pricing page. Enterprise features such as single sign-on and LDAP group synchronization are separate decisions, so budget them apart from the GitHub link itself.
How long does GitHub integration setup usually take?
No single duration applies, because setup time depends on the identity and repository work around the link. The main drivers are mapping GitHub accounts to OpenProject users, the number of repositories and projects to connect, and how many reference conventions teams adopt for OP# references. Review of security controls adds time when someone must confirm webhook secrets, token scope, who can administer the connection and how access is removed when people leave. A single-project pilot moves quickly, while a rollout across several teams takes longer because mapping and sign-off repeat for each group. Ask any provider for a written scope with a timeline tied to these items, and check the official documentation for the setup steps your version requires.
What does our team need to provide for the GitHub link?
You need four things before setup starts. First, an OpenProject server you control, reachable on the network path that GitHub webhooks will use, with TLS configured correctly. Second, a GitHub owner or organization administrator who can register the connection, approve access and manage tokens or app permissions. Third, an OpenProject administrator account to configure the integration and user mapping. Fourth, a test project with sample work packages where the first links can be checked without touching live delivery. Confirm the exact prerequisites for your OpenProject version in the official documentation, and agree in advance who owns the credentials, where they are stored and who rotates them.
Can our own engineers set up the GitHub link without a partner?
Yes. A team with experience running self-hosted services can set up the link alone by following the official OpenProject documentation and a written test plan. A partner adds the most value when many repositories and users must be mapped, when security review or audit evidence is required, or when no one on the team has run webhooks against a self-hosted instance before. A practical test plan covers: creating a test project, linking one repository, opening a pull request that references an OP# work package, confirming the work package updates, checking that Actions status appears, and confirming that users without permission cannot see the linked items. Keep the plan and results, because they become the evidence you show reviewers later.
What changes in the GitHub link after an OpenProject upgrade?
Upgrades can change behavior, configuration and database requirements, so re-run your test plan after every upgrade. Read the release notes for every version between your current release and the target, not only the newest one. The OpenProject release notes list 17.7.0 (August 5, 2026), 17.8.0 (September 2, 2026), 17.9.0 (September 30, 2026) and 17.9.2 (October 15, 2026), among others. After each upgrade, check that webhook endpoints are still reachable, that the GitHub app or token is still valid, that OP# reference parsing behaves as before and that the Enterprise features you rely on are unchanged. Confirm the PostgreSQL version too, since OpenProject supports PostgreSQL 16 or later from 16.0.0.
What usually breaks with GitHub webhooks and OpenProject?
Most failures fall into a few groups. Webhook delivery can be blocked by a firewall, reverse proxy or certificate problem between GitHub and your server. Reference formatting can differ from what teams expect, so a pull request mentions a work package but nothing updates. Identity mapping can fail when a GitHub account has no matching OpenProject user, which leaves activity unattributed. Tokens can have broader scope than needed or expire without anyone noticing. Start with the delivery history on the GitHub side, then check OpenProject application logs for the same events. Confirm the log locations and the delivery retry behavior in the official documentation for your version, and test each failure mode in the pilot project before users depend on the link.
Does DeployOpen set up the GitHub link for our organization?
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including OpenProject. Most engagements are fixed-scope, so the scope, deliverables and timeline are agreed in writing before work starts. Cost depends on what the scope includes: identity mapping, the number of repositories, security control review, testing and documentation each add work. Setup is usually one-time, while Enterprise licenses, if you choose them, recur monthly per user, and ongoing support, upgrades and continuous testing are available as retainers. DeployOpen does not publish a price list. Ask for a quote that lists the scope, assumptions, what you provide and what recurs after go-live.
How DeployOpen works on this
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted OpenProject inside your own infrastructure, including the link between OpenProject and GitHub. The GitHub connection is built around OP# references and webhooks, so pull requests and Actions status reach the work packages they belong to. Engagements are fixed-scope, with the scope agreed in writing before work starts.
How we scope
- Written scope lists which repositories, branches and OP# reference patterns the integration will cover.
- We confirm the OpenProject edition and whether the Community features cover each planned workflow.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before work starts.
How we build
- We set up webhook delivery from GitHub to OpenProject, with the endpoint, secret and event types agreed up front.
- Actions status is tested against a non-production repository before any production project is connected.
- Hosting, access and token handling run in your infrastructure, with the GitHub app or token permissions documented.
How we hand over
- Handover includes a written configuration record covering webhook endpoints, event types and reference conventions.
- Your team receives a runbook for rotating webhook secrets and tokens and for diagnosing failed deliveries.
- A test checklist shows which pull request and Actions events should appear on which work packages.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Where a retainer covers upgrades, the GitHub link can be re-tested after each OpenProject release.
- Ask whether the Community edition covers your needs and confirm any change in GitHub behavior with the vendor docs.
