Setting Up Github Webhooks, Jenkins, and Ngrok for Local Development

This tutorial will take you through the step by step process of setting up Jenkins, Ngrok, and Github Webhooks for building and testing project(s) that you have hosted on your own personal github. The environment I am using is an Ubuntu 18.04 Virtual Machine hosted on my Mac. This tutorial is specific towards users who want to try Jenkins locally without using a VPS.

Install All Necessary Dependencies

The dependencies you will need include:

• Java
• Git
• Jenkins

This website will take you through the initial process of setting up Java and Jenkins - https://linuxize.com/post/how-to-install-jenkins-on-ubuntu-18-04/. In order to install Git, run the following command in the terminal:

sudo apt install git

Setting Up and Starting Jenkins

In order to start Jenkins run the following command inside your terminal: sudo systemctl start jenkins

Run this command sudo systemctl status jenkins to make sure it’s running

You should see the active in green verifying that the Jenkins service is in fact running

In your browser of choice, Ubuntu has Firefox. Navigate to http://localhost:8080 and you should see a Jenkins unlock screen detailing where to find the default admin key. So switch to your terminal and run:

cat /var/lib/jenkins/secrets/initialAdminPassword

Copy that key and paste it in to the administrator password textfield, then click continue. Next, you will be asked to Customize Jenkins, you can just choose Install Suggested Plugins. After the plugins are installed, it may ask you to create an admin user, I highly suggest doing this in order to not have to remember that long randomly generated password.

The last screen you will see is an Instance Configuration where it will have you verify your Jenkins URL. For this I have it set as http://localhost:8080 since it will be hosted locally inside of my Virtual Machine.

Once you click save and finish you are ready to start Jenkins!

Installing and Running Ngrok

Ngrok is a reverse proxy that allows traffic to be redirected from the generated url to wherever your local server is running. It is fantastic for cases like this, where you don’t want to host a webserver and just want to try out different technologies without paying for a VPS. And there is a free tier!

So head on over to https://ngrok.com/ and signup for an account, using whichever method you choose. Then you should be greeted with the screen below showing how to unzip and run it.

After unzipping I moved ngrok to /home/michaelwakeling/ (Your user will be different than mine)

Now instead of running the command in step 4, you will run the following

./ngrok http 8080

After running the command this screen should appear, take note of the http(s) address it generates

Now open another terminal and get ready to setup some webhooks and ssh keys!

Setting Up Github Webhooks

Now in your browser navigate to your Github repository that you want Jenkins to monitor for pushes and click on Settings > Webhooks.

Make sure the URL is the one that is being output by ngrok.

Once you click Add Webhook (In my case it says update), the Github Server will send a request to your Jenkins server and if successful it will show a green check mark next to the URL when you go back to the Webhooks section of your repository.

Adding a Deploy Key for Github

In order for Github and Jenkins to communicate with one another, a deploy key is needed in order to do so. To create a deploy key go into your terminal and run sudo su -s /bin/bash jenkins this will switch the user to the Jenkins service. This step is needed or else the authentication with Github will not succeed. In order to generate a key for Github run the following:

ssh-keygen

Then keep pressing enter for the defaults and the key should be generated at

/var/lib/jenkins/.ssh/id_rsa.pub

run cat against this file and make sure to copy the entire key. Then navigate to your Github repository Settings > Deploy Keys and Add deploy key. Give it a name and paste in the copied key.

Then back to the terminal (so much back and forth), and make sure you are still the jenkins user (run whoami to verify this), run ssh git@github.com.

If all goes well you should see a message similar to this one

Sample Project to Use

After this setup is all done, you will now be able to add a new pipeline in Jenkins and have it automatically poll you Github repository for remote pushes to the master branch. Just make sure that the necessary plugins are installed if you will be building a pipeline around a NodeJS project. I have a very simple project hosted on My Github this includes the necessary pipeline file needed. If you clone this and host it on your own Github you should be able to get a working testing running in a few minutes. Just make sure you have the NodeJS plugin install for Jenkins. When creating the pipeline make sure that the Build Trigger is set to GitHub hook trigger for GITScm polling. As well as having these settings for the Pipeline portion.

Make sure the jenkinsfile is in lowercase and the repository URL points to your project’s Github URL

If that is setup correctly, whenever you push to origin master on Git it should trigger a build within Jenkins.

Note: My jenkinsfile in my project is lowercased but if you create one yourself, make sure you match the case or Jenkins may not recognize it.

Thank you for reading, if you have any questions please feel free to ask. I made this tutorial for those like me, where I had to go through several different articles and slowly piece them together in order to get this up and running properly.