How to deploy from GitHub via Jenkins on OpenShift

You may want to store your OpenShift application’s code on GitHub. We can trigger Jenkins builds from GitHub when a new commit is made using post-receive hooks and the Jenkins GitHub Plugin.

Installing the plugin

  1. On the main page of Jenkins click “Manage Jenkins”.
  2. Visit the “Manage Plugins” section.
  3. Click the “Advanced” tab, scroll to the bottom and click the “Check now” button. This will fetch the latest version information for all your plugins.

    jenkins-check-for-updates

  4. Click the “Updates” tab, select all the updates and click to download and install them after a restart.
  5. Click the “Available” tab and search for the plugin named “GitHub plugin”. Install this with the button at the bottom.

    jenkins-plugin-installation

Adding GitHub credentials to Jenkins

This is a bit fiddly, but we need to create both a GitHub username/password credential item and a “secret text” credential item using a GitHub Personal Access Token.

Adding your username/password

  1. On the main Jenkins page click “Credentials” in the sidebar.
  2. On the main Credentials page click the child item “System” in the sidebar.

    adding-github-credentials

  3. Click “Global credentials (unrestricted)” to access this credentials domain.

    global-credentials-domain

  4. Click “Add Credentials in the sidebar to add a credentials item to this domain.

    add-credentials

  5. Choose “Username with password” as the “Kind”, leave the “Scope” as “Global” and supply your GitHub username and password.

    inputting-credentials

  6. Press the “Save” button to make these username/password credentials accessible for use elsewhere in Jenkins.

Adding your Personal Access Token

  1. Navigate to Credentials > System and this time click the “Add domain” link in the sidebar.

    jenkins-add-domain

  2. Add the domain name “api.github.com” and click the “OK” button to create this domain.

    jenkins-add-domain-page

  3. Navigate to Credentials > System and click this new “api.github.com” domain.

    jenkins-access-domain

  4. Click “Add Credentials” in the sidebar to add a credentials item to this domain.

    sidebar-add-credentials

  5. Open GitHub in a new tab and generate a new Personal Access Token with the access level repo and admin:repo_hook.

    github-access-token

  6. Back in Jenkins select “Secret text” for “Kind” in the dropdown, leave “Scope” as “Global” and paste your Personal Access Token in “Secret”. Press the “OK” button to make these credentials accessible elsewhere in Jenkins.

    jenkins-secret-text

Creating the Webhook in GitHub

We want GitHub to notify your Jenkins instance whenever you push commits to the repo. We’ll use Webhooks for this.

In the “Webhooks & services” section of your GitHub repo’s settings, add a new Webhook with the Payload URL of https://jenkins-yoursitename.rhcloud.com/github-webhook/ and choose the “Content type” application/x-www-form-urlencoded.

github-adding-webhook

Configuring the plugin in Jenkins

  1. On the main Jenkins page click “Manage Jenkins”.
  2. On the Manage Jenkins page that appears click “Configure System”.
  3. Scroll down to the “GitHub” section click the “Add GitHub Server” button then “GitHub Server” which appears in the dropdown

    Adding GitHub Server to Jenkins

  4. Choose the personal access token credentials you made earlier from the dropdown, click the “Test Connection” button and ensure Jenkins is able to communicate with your GitHub account.

    jenkins-test-connection

  5. Finally click the “Save” button and your Jenkins instance will now be capable of pulling code from your repositories and deploying it to your OpenShift gears.

Configuring Jenkins to build from your repo

  1. Now your Jenkins instance has access to your GitHub account, navigate to your Jenkins build project’s configuration page.
  2. Check the “GitHub project” checkbox and provide the project URL e.g. https://github.com/yourusername/yoursitename/

    jenkins-set-github-url

  3. In the “Source Code Management” section replace the OpenShift repo SSH URL with your GitHub repo URL e.g. https://github.com/yourusername/yoursitename and choose the username/password credentials you made earlier from the dropdown.

    github-username-password-creds

  4. Choose master as the branch to build (as screenshot above) unless you have any specific requirements.
  5. Finally, scroll down to the “Build Triggers” section and click the new “Build when a change is pushed to GitHub” checkbox, then save your changes.

Now when you push to your GitHub repo Jenkins will be notified via the Webhook and a build started. It will use the GitHub repo URL you specified in Step 3 ($GIT_SSH) in the deployment script which is visible in the “Build” section at the bottom of the configuration page.

Also worth noting:

  • Make sure hot deploy is not enabled in your application, or the deployment script will stop your application but not start it again.
  • You can set up more fun stuff in Jenkins like setting the status of the GitHub commit based on the build and creating git “tags” for each of your releases.

Leave a Reply