If your job involves developing or deploying software, you've probably already heard of Jenkins, a Continuous Integration (CI) server designed specifically for automating software builds and deployments. As a leading open source project, Jenkins is extremely versatile and comes with 1000+ plugins that allow easy integration with many different platforms, source code management systems and build systems.
Oracle Cloud Jump Start makes it easy to get started with pre-configured solutions running on Oracle Cloud infrastructure, for free. The Jenkins Demo Lab in Oracle Cloud Jump Start is a one-click solution that lets you deploy a Jenkins instance on Oracle Cloud infrastructure, then use it to automate builds and deployments for your software projects.
With this guide, you will learn how to create a Continuous Integration (CI) pipeline for a GitHub project using the Jenkins Demo Lab on Oracle Cloud Jump Start. Once you've completed the steps in this guide, any changes made to your GitHub project code will be automatically and instantly built and tested by Jenkins, with appropriate success/failure indications as needed. By following the steps in this guide, you will gain a hands-on understanding of how Jenkins works and how you can use it to automate your software testing and delivery process.
Assumptions and Pre-requisites
This guide makes the following assumptions:
- You have launched a Jenkins Demo Lab on Oracle Cloud Jump Start (launch now)
- You have a GitHub account (register for free now)
Step 1: Log in to Jenkins
To begin, navigate to the Jenkins application at the IP address in your Demo Lab confirmation email. You should be prompted to log in, as shown below:
Log in with the access credentials specified in your Demo Lab confirmation email or on the Demo Lab launch page. Since this is the first time you're logging in, you will be prompted to install a recommended set of additional plugins and restart Jenkins:
These plugins are not required to complete the steps in this guide, but may be useful for other projects, so you should go ahead and install them. Once the installation process is complete and Jenkins has restarted (or if you have chosen to skip the installation), log in again if needed and you will arrive at the Jenkins dashboard, which looks like this:
The Jenkins dashboard is your primary control point for interacting with Jenkins. It includes controls for creating and running builds, inspecting build output, working with credentials and configuring Jenkins. You'll notice that at the moment, there are no projects or queued builds. You'll change that in the next step.
Step 2: Create and build a simple project
Jenkins makes it easy to automatically build, test and deploy software. It does this by allowing you to define "projects" and then specifying "steps" to build, test and deploy them. It also lets you automatically trigger builds on specific events (such as a repository change) or on a fixed schedule, and perform predefined actions (such as sending an email notification) on build success or failure.
To see how this works in practice, begin by clicking the "New Item" link in the Jenkins dashboard. You should be presented with a form to define a new project, as shown below. Enter a name for the new project (in this example, "myapp") and select "Freestyle project" as the project type. Click "OK" to proceed.
You should now see the project configuration page, which allows you to define various aspects of the build. For the moment, leave everything at default values and head for the "Build" section. Click the "Add build step" button and add a step to "Execute shell".
In the resulting "Command" box, enter a shell command that displays output, like the one below, and click "Save" to save the changes:
echo "Hello from Jenkins!"
Head back to the project page and click the "Build now" link.
Jenkins should begin building the project. The "Build History" panel in the bottom left corner of the page will show you the status of the build (blue indicates success, red indicates failure).
Once the build is complete, select the "Console Output" menu item to access a detailed build log. The build log should display the output of the shell command you specified earlier.
Congratulations! You just completed your first successful build with Jenkins.
Step 3: Build a GitHub project
Now that you know the basics of using Jenkins, let's look at a more "real world" example: building a project stored in an external SCM, such as GitHub. You'll use the simple Java + Maven application included with the Jenkins user documentation for this.
Begin by logging into GitHub with your account and browsing to the repository for the example Java + Maven application. Click the "Fork" button to create your own personal fork of the repository.
Note the GitHub clone URL for your fork of the repository.
|NOTE: This guide uses a simple Java project hosted on GitHub as an example. However, you can follow the steps described here for any public GitHub project, remembering to ensure that all the necessary build tools are correctly configured in Jenkins.|
The example project requires Maven and so, before you can build it, you must install Maven in Jenkins.
Log in to Jenkins (if you're not already logged in) and click the "Manage Jenkins" link to get to the Jenkins administration panel. Select the "Global Tool Configuration" option.
On the "Global Tool Configuration" page, find the "Maven" section and click the "Add Maven" button. Enter a name for the new Maven installation (here, simply "Maven") and ensure that the "Install automatically" button is ticked. Click "Save" to save the changes and install Maven.
Once Maven is installed, you can proceed to configure Jenkins to download and build the example application.
Back at the Jenkins dashboard, select the project you created in Step 2 and click the "Configure" button for the project.
On the project configuration page, in the "Source Code Management" section, select "Git" as the option and enter the clone URL for your GitHub repository.
On the same page, in the "Build" section, remove the "Execute shell" build step created in Step 2, by clicking the red "X" in the top right corner of the section.
Add a new build step to "Invoke top-level Maven targets".
- In the "Maven Version" field, select the name of the Maven installation you just created.
In the "Goals" field, specify the Maven goals as follows:
Click "Save" to save the changes.
Head back to the project page and click the "Build now" link. Jenkins should clone your GitHub repository and build it with Maven. Once the build is complete, select the "Console Output" menu item (as done previously in Step 2) to access detailed build information.
Step 4: Create a Continuous Integration pipeline for a GitHub project
The next step is to create a Continuous Integration (CI) pipeline that connects your GitHub repository with Jenkins. Once this is in place, any changes to your GitHub repository will trigger a new build in Jenkins. Any errors resulting from the changes will result in a build failure, giving you an immediate heads-up on potential issues or bugs.
To set up this pipeline, you will first enable the GitHub hook trigger in Jenkins for your project. Then, you will configure GitHub to automatically notify Jenkins on any change to the repository.
Begin by logging in to Jenkins (if you're not already logged in) and visiting the project configuration page. In the "Build Triggers" section, enable the "Github hook trigger for GITScm polling" and save the changes.
Next, log in to your GitHub account (if you're not already logged in) and browse to the "Settings" page for your repository.
In the "Integrations and services" section, click the "Add service" button and select the "Jenkins (GitHub plugin)" integration.
On the integration detail page, enter the URL to your Jenkins installation with the additional /github-webhook/ suffix. For example, if your Jenkins installation is available at http://SERVER-IP/jenkins, enter the Jenkins hook URL as http://SERVER-IP/jenkins/github-webhook/. Ensure that the "Active" checkbox is ticked and click the "Add service" button.
NOTE: It may take a few minutes for the integration to begin working.
Your pipeline is now configured, and all that remains is to test it. To do this, make a change to the repository - for example, by adding a line to the README file and committing the change.
Your change should trigger a new build in Jenkins, as shown below:
Clicking the build number will show you the details of the commit that triggered the build:
Congratulations! Your CI pipeline is now complete, and any subsequent changes to the repository will be automatically built by Jenkins.
After completing the previous steps, you should now have a good understanding of how Jenkins works, how to configure a project in Jenkins, and how to integrate Jenkins with GitHub. You should also have a working CI pipeline between your GitHub code repository and your Jenkins instance running on Oracle Jump Start.
What you've seen so far is just the tip of the iceberg. Jenkins is an extremely versatile application and you can adapt it to almost any use case or build/test requirement. Learn more about Jenkins and the other topics discussed in this guide by visiting the following links: