Introduction

Redmine is an open source project management software widely used in Japan. You can register tasks etc. in "Tickets", display them in Gantt charts, calendars, etc., set priorities, etc., and manage project progress with rich functions. There are plenty of function extensions using plug-ins, and it can be used separately from GitHub's Issues function by linking with GitHub. You can synchronize the status by linking GitHub issues and Redmine tickets, and you can check changes in repositories in GitHub and user information that made those changes from Redmine.

GitHub has used a feature called "GitHub Services" or "GitHub Webhooks" as a mechanism for integrating with other tools. However, support for one of them, ``GitHub Services'', will be discontinued after October 2018 as announced below.
https://developer.github.com/v3/guides/replacing-github-services/

There are many cases where "GitHub Services" is used to link with Redmine, but in the future it will be necessary to use "GitHub Webhooks" when linking with external services. We'll show you how to work with us.

Timeline for deprecation of GitHub Services

～GitHub Enterprise～
From GitHub Enterprise 2.17 (scheduled to be released after 2019), you will not be able to install or configure GitHub Services. GitHub Enterprise released after October 1, 2018 will be supported with GitHub Services until October 1, 2019.

～GitHub.com～
October 1, 2018: GitHub Services is no longer installable and has been removed from the UI.
January 31, 2019: You will not be able to link with the installed GitHub Services.

The figure above shows the setting screen of GitHub Services, which supports various tools.
Deprecated after GitHub Enterprise 2.17.

What are webhooks

Webhooks is a function that can send event contents to the outside via HTTP, starting from events on GitHub. You can set events to send Webhooks for each Repository. For example, when an event occurs such as when a project is pushed to a Git repository or when a pull request is created, an event can be sent to a cooperating tool.

The image above sets the webhook to be sent only on push events.

What can be done by linking GitHub and Redmine?

1. You can view Commit information of GitHub on Redmine.

You can check the difference of Commit in Redmine.

2. When committing on GitHub, if you include a specific keyword in the commit message, you can associate it with the Redmine ticket. (The "refs" keyword in the figure below is set to be recognized by Redmine in advance)

If you commit on GitHub as follows,

Commit will now appear in the Redmine ticket.

3. You can also change the status of Redmine tickets by including keywords in the commit message when committing on GitHub. (The following "Close" keyword is already recognized by Redmine)

If you commit on GitHub in the same way as in the previous section,

Redmine ticket status is changed.

Link setting procedure for GitHub and Redmine

Here, we will explain the settings necessary for linking GitHub Enterprise and Redmine.

premise

• Install Redmine 2.0 or above on Unix/Linux
• Latest version of Git

Install the Redmine GitHub Hook plugin

1. Work on the server where Redmine is installed.

2. Go to Redmine directory and in Gemfile.local file
gem "redmine_github_hook"  is added as shown below.

Gemfile.local or Gemfile

3. Execute the bundle command.

4. Restart the Redmine service.

5. Check the installation status of the plugin.

http(s)://[redmine-hostname]/admin/plugins

Redmine settings

1. Connect to Redmine server with redmine user.

2.Move to the directory that manages the Git repository.

3. Clone the GitHub Enterprise repository with the “mirror” option.
$ git clone --mirror git@[github-hostname]:owner/repository.git

※Notes

Please note that git requires SSH protocol connection. If git clone fails, please check if the user has Read permission for the repository.

①Redmineホスト端末にてパスワード無しのSSH鍵の生成する
ssh-keygen -t rsa -b 4096 -C your_email@example.com

② Register the contents of the generated SSH public key (id_rsa.pub) to your GitHub account
http(s)://[github-hostname]/settings/keys

③ Execute git clone on the Redmine server and check the operation
$ git clone --mirror git@[github-hostname]:git_user/project.git

4. Move to the cloned repository directory and try to update with the “git fetch” command.
$ cd project.git
$ git fetch -q --all -p

If the plugin (Redmine GitHub Hook) does not work well, you can check it on the official page of the plugin (in English).
https://github.com/koppen/redmine_github_hook

Add GitHub repository to Redmine

1. Select a Redmine project or create a new one.

2. Create a new repository in the project settings.

3. Set your version control system to Git. Enter the Git repository path in Repository path.

4. Check the project's repository and see if the Commit history is displayed.

Github settings

1. Go to your repository's settings and add a webhook. The setting requires admin privileges for the repository.

2. Enter the Payload URL in the following format:
http://[Redmine-hostname]/github_hook?project_id=[Redmine-projectname]

In the “Which events would you like to trigger this webhook?” item, specify the event that the webhook will be sent. This time only push event is set.

3. After registering the webhook, a test webhook will be sent, so check if it is sent correctly from “Recent Deliveries” on the same screen.

operation check

1. Commit.

2.The Commit is reflected in Redmine.

revision

You can check the difference of Commit in "Latest Revision"

Tying tickets and commits

If you include one of the keywords "refs, references, IssueID" and the ticket number in the commit message on GitHub, you can associate the issue and the commit on Redmine.

1. You can check and set the keyword from "Management" ⇒ "Settings" at the top.

2. Commit by including "refs # ticket number (Redmine)" in the commit message.

3. Then the Commit associated with the "related revision" of the Redmine ticket will be displayed.

Ticket status change

You can change the Redmine ticket status by including the specified keyword in the Commit message.

1. You can specify keywords and status in Redmine's top "Administration" ⇒ "Settings".

2. Include the specified keyword "Close #Redmine ticket number" in the commit message.

3. Then the status of the Redmine ticket will be changed.

4. There are various types of status such as "New, In progress, Resolved", so please try each.

in conclusion