GitHub Webhook Adapter

This page introduces the GitHub Integration feature provided by the GitHub Webhook Adapter plugin.

This feature integrates commit information from GitHub repositories with Redmine issues using GitHub webhooks and Redmine’s repository features.

Table of Contents

What is GitHub Integration?

GitHub Integration uses GitHub webhooks and Redmine’s repository features to integrate commit information from GitHub repositories with issues.

You can use features such as associating commits with issues and updating issue statuses based on commit messages.

How It Works

This feature works by receiving commit information pushed to a GitHub repository via GitHub webhooks.

The information Redmine receives is limited to the commit information available from GitHub webhooks.

Due to this design, the feature has the following characteristics:

  • Repository information other than commits, such as file contents, branch information, and statistics, cannot be viewed directly in Redmine.
  • Commits pushed before the integration was set up cannot be integrated.
  • If you are using the IP Address Filter, you need to add GitHub’s IP addresses to the allowlist. See Using with the IP Address Filter for details.

What You Can Do

Integrating Issues and Commits via Commit Messages

You can use Redmine’s built-in commit message integration features.

  • Associate commits with issues: Using referencing keywords such as refs #123 associates commits with issues, allowing you to track source code changes related to each issue.
  • Update issue status and progress: Using a fixing keyword updates the issue’s status and progress.
  • Log time on an issue: Writing the time alongside the issue number, such as refs #123 @2.5h, logs time on the issue according to your settings.

The available keywords, behavior when updating issues, and whether time is logged depend on your Redmine settings. These can be configured under Administration → Settings → Repositories.

Note
For issue updates and time logging to be attributed to the correct user, the commit author must be mapped to a Redmine user. See Mapping Commit Authors to Redmine Users for details.

Opening GitHub Commit Detail Pages

A link to the GitHub commit detail page is displayed in the issue’s Associated revisions section and on the revision detail screen. You can open the GitHub commit detail page directly from these links.

What Is Not Supported

The following features are not available:

  • Browsing repository information in Redmine, including file contents, per-file history, and details
  • Viewing commit details and diffs in Redmine
  • Viewing repository statistics

Limitations

Due to how this feature works, there are some limitations.

Commits Pushed Before the Integration Was Set Up Cannot Be Integrated

Because commit information is received and imported via GitHub webhooks, commits pushed before starting the integration cannot be integrated.

Failed Webhook Deliveries Must Be Redelivered Manually Within the Retention Period (3 Days)

For various reasons, commit information from GitHub webhooks may not be received successfully.

You can check webhook delivery status and redeliver failed webhook deliveries on the GitHub repository’s webhook Recent Deliveries page. However, since GitHub retains delivery history for 3 days, you must redeliver within that period.

See Redelivering Commit Information from GitHub Webhooks for details.

Additional Configuration Is Required When Using the IP Address Filter

If you are using the IP Address Filter, you must allow access from GitHub webhooks.

See Using with the IP Address Filter for details.

GitHub Enterprise Server Is Not Supported

This feature currently supports only repositories on github.com. GitHub Enterprise Server is not supported.

Getting Started

1. Allow GitHub IP Addresses If You Are Using the IP Address Filter

If you are not using the IP Address Filter, you can skip this step.

If you are using the IP Address Filter, follow the steps in Using with the IP Address Filter to allow GitHub’s IP addresses.

2. Enable GitHub Webhook

Under Administration → Settings → Repositories in Redmine, enable GitHub Webhook as a version control system.

Administration → Settings → Repositories

3. Enable the Repository Module for Your Project

In the settings screen of the project where you want to use this integration, enable the Repository module.

4. Add a GitHub Webhook Repository

From the project’s repository settings, add a new repository and select GitHub Webhook as the version control system.

For the Repository URL, enter the URL of the GitHub repository you want to connect to Redmine.

https://github.com/owner/repository

After saving the repository, a Webhook URL and Webhook Secret are generated for configuring the GitHub repository webhook.

Copy these values or keep this screen open as you proceed to the next step.

5. Add a Webhook to Your GitHub Repository

In the GitHub repository’s webhook settings, enter the Webhook URL and Webhook Secret generated in the previous step.

Setting Value
Payload URL Set the Webhook URL.
Content type Select application/json.
Secret Set the Webhook Secret.
SSL verification Select Enable SSL verification (default).
Events Select Just the push event (default).
Active Enable.

For instructions on creating a webhook on GitHub, also refer to the GitHub documentation .

6. Verify the Connection

After creating the webhook, verify the connection on the GitHub repository’s webhook page.

If a green checkmark is displayed, the configuration is correct. It may take some time before the result appears. If so, reload the page a few times.

If a warning mark is displayed, you need to review and correct the configuration.

Follow the steps in Redelivering Commit Information from GitHub Webhooks to fix the configuration. After making corrections, verify the connection again using the following steps:

  1. Open the webhook edit page and go to the Recent Deliveries tab.
  2. Click the ping delivery entry, then click the Redeliver button to send another ping to Redmine.
  3. Confirm that the ping succeeds. If it fails, repeat the steps above to fix the configuration.

Viewing Received Commits

All commits received from GitHub webhooks can be viewed on the received commits list screen.

You can also use this screen to search for commits and manually associate them with issues.

Mapping Commit Authors to Redmine Users

Commit authors are automatically mapped to Redmine users when their login name or email address matches. If there is no match, you need to configure the mapping manually.

This mapping is required for issue updates and time logging via commit messages to be correctly attributed to the committing user.

  • Issue updates via commit messages: Available even without a mapping, but the update is recorded as an anonymous user’s action.
  • Time logging via commit messages: Not available if no mapping is configured.

You can check the mapping status and configure it manually from the Users section in your project’s repository settings.

Regenerating the Webhook URL and Webhook Secret

You can regenerate the Webhook URL and Webhook Secret, which are automatically generated when a repository is registered, from Redmine’s repository edit screen.

After regenerating, you need to update the Payload URL and Secret in the GitHub repository webhook settings with the new values.

Important
Webhook deliveries cannot be received until the settings are updated.

Using with the IP Address Filter

If you are using the IP Address Filter, you must add the IP addresses that GitHub uses for webhook deliveries to the IP Address Filter allowlist.

The IP addresses that GitHub uses for webhook deliveries can be retrieved using the Meta API endpoint GET /meta.

Add the IPv4 addresses listed under hooks in the response to the IP Address Filter allowlist.

The following command is the macOS/Linux example from the GitHub documentation.

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/meta

The response looks like the following:

{
  ...
  "hooks": [
    "192.30.252.0/22",
    "185.199.108.0/22",
    "140.82.112.0/20",
    "143.55.64.0/20",
    "2a0a:a440::/29",
    "2606:50c0::/32"
  ]
  ...
}

The response shown above is an example and may differ from the current values. When configuring the IP Address Filter, use the latest IP addresses returned by the API.

For details, see the GitHub documentation.

Troubleshooting

Redelivering Commit Information from GitHub Webhooks

You can check webhook delivery status and redeliver webhook deliveries on the GitHub repository’s webhook Recent Deliveries page. However, you can only redeliver the last 3 days of deliveries stored on GitHub. For details, see the GitHub documentation.

Check the delivery status, and take action if there are any failed deliveries.

Check the response code shown in the Response field, such as 400, and take the corresponding action described below. After taking the action, click the Redeliver button to resend the delivery.

400

Cause Action
The Content type in the GitHub repository webhook settings may not be set to application/json. Update it to application/json.
The Repository URL in Redmine's repository settings may not match the target GitHub repository URL. Update it to the correct GitHub repository URL.

401

Cause Action
The Secret in the GitHub repository webhook settings may be incorrect. Regenerate the Webhook Secret and update the settings.

403

Cause Action
If you are using the IP Address Filter, access from GitHub may have been denied. Follow the steps in Using with the IP Address Filter to allow GitHub's IP addresses.

404

Cause Action
The Payload URL in the GitHub repository webhook settings may be incorrect. Regenerate the Webhook URL and update the settings.

Other Response Codes

For any other response code, wait a moment and try again using the Redeliver button.

Also, if no matching deliveries appear in the delivery list, no webhook delivery was sent from GitHub. Check on GitHub and confirm that:

  • The target commit was pushed to the repository.
  • The webhook is configured to deliver push events.