Home Tutorials Training Consulting Products Books Company Donate Contact us









NOW Hiring

Quick links

Share

Using Github tutorial. This tutorial explains how to use GitHub.

1. GitHub

1.1. What is GitHub?

GitHub is a popular hosting provider for Git repositories. GitHub provides additional services around these repositories. For example, it provides an issue tracker for each repository, build server integration and more.

GitHub supports that repositories can be cloned to a new Git repository hosted at Github. GitHub uses the term fork or forking for creating such clones.

GitHub provides free hosting for publicly visible Git repositories. A public repository can be cloned by other people at any point in time.

If the repository should not be visible to everyone, Git allows to create private repositories, but you must pay for this service a monthly rate. Private repository allows you to specify the people which have access to the repository and to define their access rights.

GitHub can be found under the following URL: GitHub

If you create an account at GitHub, you can create a repository. After creating a repository at GitHub, you will get a description of all the commands you need to execute to upload your project to GitHub. Follow the instructions below.

These instructions will be similar to the following commands.

# global setup:
#  set up git
  git config --global user.name "Your Name"
  git config --global user.email your.email@gmail.com

# next steps for a new repository
  mkdir gitbook
  cd gitbook
  git init
  touch README
  git add README
  git commit -m 'first commit'
  git remote add origin git@github.com:vogella/gitbook.git
  git push -u origin master

# alternatively for an existing Git repo
# add remote and push
  cd existing_git_repo
  git remote add origin git@github.com:vogella/gitbook.git
  git push -u origin master

GitHub allows you to use SSH based or HTTPS based authentication to access your repositories. To clone, pull or fetch from a public available repository no authentication is required.

1.2. Create repository in GitHub

Once you create a user at Github, you can create a new public repository. For example, the following screenshots demonstrate the creation of the de.vogella.git.github repository.

Creating GitHub repository step 1
Creating GitHub repository step 2

After creation of your new repository GitHub displays the information what you have to do if you want to connect to this repository via the command line.

1.3. Merging pull request at GitHub

GitHub uses Pull requests for contributions.

The typical workflow in GitHub is to fork a repository, create changes in your fork and send a pull request to the origin repository via the GitHub webinterface.

GitHub makes is easy to fork a repository via its web interface. Simply click the Fork button of a repository of your choice.

Forking a GitHub repository

You can now clone this fork to your local development environment and push the changes to this fork at GitHub.

Afterwards you can create a pull request for the repository you forked from. Your repository is the fork as highlighted in the screenshot. Press Pull Requests to see existing and create new pull requests.

Creating a pull request for Github

Click New pull request to create a new one.

Creating a pull request for Github

On the next screen you can specify the direction of the pull request and the branches by selecting the Edit button.

Creating a pull request from Github

If the owner of the repository accepts your pull request, your changes are integrated into the original repository.

1.4. Locally evaluating Github pull requests

You can also pull the changes in a Github pull request into your local Git repository to test it. Each pulll request has a link which once clicked shows you the corresponding commands.

Getting the changes of a Github Pull request into your local repo

2. Closing issues with commit messages

Github allows you to close issues with commit messages by using special keywords. Github will put a link to the closing commit into the specified issue. While it is possible to use this syntax anywhere in the commit message it is preferable to put it into the commit subject. This way it is easier to see which commit closes which issue.

2.1. Closing issues in the same repository

To close an issues in the same repository you type in one of the keywords followed by a reference to the issue number. List of possible keywords:

  • close

  • closes

  • closed

  • fix

  • fixes

  • fixed

  • resolve

  • resolves

  • resolved

This is a commit message that would close issue 42 in the same repository:

Fixes #42 - Upgrade SWT dependencies

If the issue is commited to the default branch the issue will be closed immediately. If the issue is commited to another branch then the issue will only be closed if it gets merged into the default branch. This behaviour is the same for closing issues in other repositories.

2.2. Closing issues in other repositories

The syntax to close issues in other repositories is username/repository#issue_number. So our example from before would look like this for the repository project by the user vogellacompany.

Fixes vogellacompany/project#42 - Upgrade SWT dependencies

2.3. Closing multiple issues with one commit

If you want to close multiple issues with one commit just chain the messages together. Each message follows the pattern <keyword> <issue>.

This closes #42, closes #23, and closes vogellacompany/project#42

3. Continuous Integration with Github and Jenkins via webhooks

Often we want to automatically start a build on our build system after changes to a repository. If you want to trigger a Jenkins build after every update on your GitHub repository you can use webhooks.

To do this navigate to the repository you want your webhook for and click on Settings ▸ Integrations & services. Click on Add Service and choose the Jenkins (Github Plugin) integration.

Select Jenkins (Github Plugin) Service

The Jenkins webhook url follows the pattern <Jenkins url>/github-webhook.

Set your Jenkins webhook url

Now add the Jenkins GitHub Plugin to your Jenkins instance. Make sure you have your Jenkins build correctly configured for the GitHub repository. Navigate to the Configure page of your Jenkins build. Under "Build Triggers" choose the option "Build when a change is pushed to GitHub".

Set jenkins build trigger

After your next commit to the repository a new Jenkins build should start automatically.

4. Using Gerrit through GerritHub

GerritHub is a service that allows you to use Gerrit for code reviews for your GitHub repositories. It works by cloning your repositories to it’s servers and allows you to push Gerrit changes to them. Merged Gerrit changes are synced back to GitHub. Once you have imported a repository to GerritHub it is best to stop pushing to GitHub as GerritHub only syncs in one direction. You can still push commits directly to the repository on GerritHub without starting a Gerrit change. Those commits will also be synced back to GitHub.

4.1. Authorizing GerritHub

To use the service you have to Sign in with your GitHub account. Open up http://gerrithub.io and press First time Sign In.

First time Sign In button

On the next page choose Sign In to log in with your GitHub account.

Sign In button

You can then choose if you want to give GerritHub access to your private or only your public repositories. GerritHub then asks for the following authorizations:

  • Read-only access to your email adresses

  • Read and write acess to your public (and possibly private) repositories

  • Read-only access to your organizations You have to accept to proceed.

After finalizing your account information you are then ready to use GerritHub. In the next step you can choose which repositories you want to import and have the possibility to import existing pull requests.

4.2. Importing a repository from GitHub

To import a repository from GitHub, first open Gerrit on GerritHub: https://review.gerrithub.io. Now choose GitHub ▸ Repositories.

Import repositories link

Select all repositories that you want to import and click on the Next button. The next page lets you select which existing pull requests you want to import as Gerrit changes.

4.3. Importing pull requests from GitHub

It is possible to import existing pull requests from GitHub as Gerrit changes. Please be aware that changes made to the pull request after the import won’t propagate to the Gerrit change. You can import the pull request again but this will create a new Gerrit change instead of updating the old Gerrit change.

To import pull requests from GitHub open Gerrit on GerritHub: https://review.gerrithub.io. Now choose GitHub ▸ Pull Requests.

Import pull requests link

Select all pull requests you want to import and then press the Next button.

4.4. Pushing a commit to GerritHub for code review

Once you have imported your GitHub resources into GerritHub you can use it like any other Gerrit instance. After you merged a change GerritHub will automatically try to push it back to GitHub. For information on how to use Gerrit please see our Gerrit tutorial.

4.5. Keeping the repositories in sync

If you are only using GerritHub to push changes you don’t have to do anything additional. GerritHub automatically propagates merged changes back to GitHub. If you or someone else pushes changes directly to GitHub you have to manually sync this changes to GerritHub. Assuming you have set GitHub as your origin remote and gerrithub as your GerritHub remote:

git pull master
git push gerrithub master

4.6. Build validation with Jenkins

It is possible to trigger a new build by every patch set that gets uploaded to Gerrit. This way you can be confident that changes submitted through Gerrit won’t break your build. It is recommended to use an extra Jenkins user for Gerrit.

Create a new GitHub user for your Jenkins instance and link it with GerritHub as described in Authorizing GerritHub. Make sure to add the public ssh key of the Jenkins to this account at https://review.gerrithub.io/#/settings/ssh-keys.

Now give the Jenkins user the rights to change the Verified label. You can do this by editing your project configuration file:

[access "refs/*"]
    <other entries...>
    read = group user/<Jenkins User Id>
[access "refs/heads/*"]
    <...>
    label-Verified = -1..+1 group user/<Jenkins User Id>

Now install the Gerrit Trigger plugin onto your Jenkins instance. The Gerrit Trigger plugin works by listening to the Gerrit event stream. This way the Gerrit server doesn’t have to specifically know about the Jenkins server. It is enough to give the Jenkins user the required access rights to the Jenkins project. If you want to check out the event stream yourself you can listen to it with this command:

ssh -p 29418 <your jenkins user>@review.gerrithub.io gerrit stream-events

The next step is to add GerritHub to the Gerrit Trigger configuration. Navigate to Manager Jenkins ▸ Gerrit Trigger and add a new server:

Hostname: review.gerrithub.io, Frontend URL: https://review.gerrithub.io/, Port: 29418

Before saving hit the Test Connection button to make sure you entered the right information.

Now you can change your desired project to include a Gerrit trigger. Open up Project ▸ Configure and choose "Gerrit event" under "Build triggers". Select the server that we created earlier from the drop down menu. For this example we have chosen to name our project "hello_world". We match on it by adding a project of type "Plain" and writing down the exact project name. The project name follows the pattern <jenkins user name>/<project name>. To match all branches on the project we choose the type "RegExp" and enter .*. By not adding anything under "Trigger on" we let the plugin add the default triggers "Patch set created" and "Draft published".

Jenkins Project configuration page with Gerrit Trigger configuration

The next step is to configure the Git plugin, so the build job knows which repository to fetch and build. As "Repository URL" we enter the the GerritHub project url. It follows the pattern ssh://<GerritHub jenkins user>@review.gerrithub.io:29418/<project owner user>/<project name>. Press the Advanced button and enter $GERRIT_REFSPEC as "Refspec". As branch to build enter $GERRIT_BRANCH. Under "Additional Behaviors" add an "Strategy for choosing what to build" entry and choose "Gerrit Trigger" from the drop down menu.

Gerrit Trigger Git configuration

As last step your should add the appropriate build step for your project.

To test your configuration create a new Gerrit change or upload a new patch set to an existing change. The Jenkins build server should give you feedback now:

Jenkins build server setting -1 verified flag

5. About this website

6. Links and Literature

6.1. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT

The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”.

The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.

Copyright © 2012-2017 vogella GmbH. Free use of the software examples is granted under the terms of the EPL License. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.

See Licence.