{"id":21129057,"url":"https://github.com/ics-software-engineering/play-example-continuous-integration","last_synced_at":"2025-07-08T19:35:50.550Z","repository":{"id":9356013,"uuid":"11208587","full_name":"ics-software-engineering/play-example-continuous-integration","owner":"ics-software-engineering","description":"How to do CI with GitHub, CloudBees, and the Play Framework","archived":false,"fork":false,"pushed_at":"2013-07-11T00:25:39.000Z","size":3583,"stargazers_count":9,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-02T06:27:53.814Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ics-software-engineering.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-05T21:12:57.000Z","updated_at":"2023-11-25T04:21:35.000Z","dependencies_parsed_at":"2022-09-22T16:22:30.819Z","dependency_job_id":null,"html_url":"https://github.com/ics-software-engineering/play-example-continuous-integration","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ics-software-engineering/play-example-continuous-integration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-continuous-integration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-continuous-integration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-continuous-integration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-continuous-integration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ics-software-engineering","download_url":"https://codeload.github.com/ics-software-engineering/play-example-continuous-integration/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-continuous-integration/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264334497,"owners_count":23592435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T05:14:46.170Z","updated_at":"2025-07-08T19:35:50.503Z","avatar_url":"https://github.com/ics-software-engineering.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"Summary\n=======\n\nThe goal of this project is to illustrate how to set up a [Play](http://playframework.com) application, \nhosted on [GitHub](http://github.com), \nto use [CloudBees](http://cloudbees.com) for [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration). In addition, it illustrates how to incorporate \nquality assurance tools ([Checkstyle](http://checkstyle.sourceforge.net/), [PMD](http://pmd.sourceforge.net/), [FindBugs](http://findbugs.sourceforge.net/), and [Jacoco](http://www.eclemma.org/jacoco/)) into continuous integration.\nFinally, it also illustrates how to trigger deployment from your CI process.\n\nNote that this procedure is tedious and complicated the first time you do it.  Luckily, \nonce you have successfully set up your first Play application on GitHub to use CloudBees for CI,\nyou can use it as a template for setting up future projects, and the procedure is much, much faster and easier.\n\nContinuous integration between CloudBees and GitHub requires several different uses of public and \nprivate keys.  To help provide intuition on their use, I wrote a blog post on \n[Introduction to public key authentication for git users](http://philipmjohnson.wordpress.com/2013/07/08/introduction-to-public-key-authentication-for-git-users/). \nIf you are not feeling confident with the use of public and private keys, you may find this posting to be useful.\n\nI've divided this procedure into two parts: a \"One Time Configuration\" (OTC) part containing steps you have to\nperform only once on your GitHub and CloudBees accounts, and a \"Per Project Configuration\" (PPC) part that\nyou have to do every time you want to put a new project under continuous integration.   Here's an overview:\n\n**Overview of One Time Configuration (OTC)**\n  1. Set up your GitHub account and host your Play application\n  2. Set up your CloudBees account and create a sample Play application \n  3. Configure CloudBees Jenkins plugins\n  4. Tell GitHub your CloudBees public key\n\n**Overview of Per Project Configuration (PPC)**\n  1. Prime the CloudBees pipeline\n  2. Make CloudBees Jenkins job point to GitHub repo\n  3. Configure build trigger\n  4. Test your continuous integration and deployment\n  5. Automate quality assurance tool invocation (optional)\n     \nLet's now look at each of these steps in detail.\n\nOne Time Configuration (OTC) Steps\n==================================\n\nThe following steps need to be done only once; they constitute the \"global\" configuration \nprocess for both GitHub and CloudBees for use as CI for Play applications.\n\nOTC Step 1: Set up your GitHub account and host your Play application\n---------------------------------------------------------------------\n\nBegin by setting up an account on GitHub and hosting your Play application using it.  Follow the \n[excellent instructions](https://help.github.com/articles/set-up-git) if you \nhaven't done this before.  \n\nYou might want to fork the play-example-continuous-integration repo if you want to quickly set up a basic Play application \nwith which to play with continuous integration.   This repo also includes the quality \nassurance tool enhancements documented in [play-example-quality-assurance](http://ics-software-engineering.github.io/play-example-quality-assurance/).\n\nOTC Step 2: Set up your CloudBees account and create a sample Play application\n------------------------------------------------------------------------------\n\n**OTC Step 2.1: Create a ClickStart Play Application**\n\nNow set up an account on CloudBees. After you have created your account, use [ClickStart](https://developer.cloudbees.com/bin/view/RUN/ClickStart) \nto automagically create a sample Play application.  While running the Play ClickStart, CloudBees will:\n  * Create a git repo to hold the source for the sample app.\n  * Create a database connected to the sample app.\n  * Set up a Jenkins build job for the sample app.\n  * Build the sample app using the Jenkins job.\n  * Deploy the sample app to the CloudBees hosting platform.\n  \nGetting all this done automatically is, clearly, pretty sweet, and you'll want to keep this sample app around for reference purposes. \nDoing the ClickStart also provides a sanity check that you can create, build, and deploy Play apps\non CloudBees.\n\n**OTC Step 2.2: Install CloudBees SDK (optional)**\n\nAlthough it does not appear to be strictly necessary for CI, it can be helpful to \ninstall the [CloudBees SDK](http://developer.cloudbees.com/bin/view/RUN/BeesSDK), since it \nprovides command-line access to your CloudBees projects. \n\nTest your SDK installation by downloading the code for the sample Play app you created using ClickStart to your local\nworkspace. To do this successfully, you will need to provide your public key to CloudBees so it\ncan authenticate you when you pull the code using git. Here are some useful references:\n  * [How to set your public key for git access in CloudBees](http://wiki.cloudbees.com/bin/view/DEV/How+to+set+your+Public+Key+for+Git+Access)\n  * [Git Troubleshooting on CloudBees](http://wiki.cloudbees.com/bin/view/DEV/Git+-+Getting+Started#HTroubleshooting)\n  * [Help for \"Permission denied (public key)\"](https://help.github.com/articles/error-permission-denied-publickey)\n  \nOnce you've downloaded your sample Play app, invoke \"play test\" to see that the system compiles and \nruns its tests successfully in your local environment.  \n   \nOnce you are comfortable manipulating this \"vanilla\" version of a Play application on CloudBees, it is now time\nto start customizing it for continuous integration with GitHub.\n\nOTC Step 3: Configure CloudBees Jenkins plugins\n-----------------------------------------------\n\n**OTC Step 3.1: Install GitHub plugin**\n\nIn CloudBees, click on the \"Builds\" button in the nav bar to bring up your Jenkins instance, then \nclick on \"Manage Jenkins\" in the left side menu bar. This brings you to the following page:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/manage-jenkins.png\"/\u003e\n\nClick on \"Manage plugins\", click on \"Available\", find \"GitHub Plugin\", and then install and restart your Jenkins instance.\nAfter doing that, you should see the following near the bottom of the list of \"Installed\" plugins in Jenkins:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/github-plugin.png\"/\u003e\n\nNow go back to the \"Manage Jenkins\" page, and instead of clicking on \"Manage Plugins\", click on \n\"Configure System\". You'll find a \"Git plugin\" section halfway down the page. Provide your user.name\nand user.email values as illustrated below:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/git-plugin-config.png\"/\u003e\n\nScroll down to the bottom of the page, and make sure that \"Manually manage hook URLs\" is selected:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/manually-manage-hook-url.png\"/\u003e\n\n\n**OTC Step 3.2: Install QA plugins (optional)**\n\nPart of the allure of continuous integration is the ability to run quality assurance tools such \nas Checkstyle, PMD, FindBugs, and Jacoco in the cloud and to see trends in the issues reported\nby those tools over time. To provide good reporting on these tools, you will want to install their\nassociated plugins as well.  This is an optional step.\n\nFollowing the same process as before, go to the \"Manage Jenkins\" page, click on \"Manage Plugins\", \nand install the \"Static Analysis Utilities\", \"Static Analysis Collector Plug-in\", \"FindBugs Plug-In\", \n\"Jenkins JaCoCo Plugin\", \"PMD Plugin\", and \"Checkstyle Plugin\". Restart Jenkins. When all of these have been \ninstalled, the \"Available\" tab in the Manage Plugins page should contain the following:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/qa-plugins.png\"/\u003e\n\n**OTC Step 3.3: Install and configure build status badge (optional)**\n\nIt's nice to be able to display the status of the build in your GitHub page.  Here's \nan example from the bottom of the [play-example-quality-assurance project's README page](https://github.com/ics-software-engineering/play-example-quality-assurance):\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/build-status-badge.png\"/\u003e\n\nIf you want this (and of course you do), you must first install the \"embeddable-build-status\" plugin\nto Jenkins.  Go to \"Manage Jenkins\", then \"Manage Plugins\", then install embeddable-build-status.\nRestart Jenkins.  Once Jenkins has restarted, you should see the following near the bottom of the \n\"Available\" tab in the Manage Plugins page:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/embeddable-build-status.png\"/\u003e\n\nNow you must configure Jenkins to support anonymous access by following the instructions [here](https://developer.cloudbees.com/bin/view/DEV/AnonymousAccess).\nIn brief, you must:\n  1. Provide the Jenkins anonymous role with \"Job/Read\" access.\n  2. Flip the switch for anonymous access by going to \"Manage Jenkins\", then \"Configure System\", then clicking \"Enable read-only access for anonymous users\", and finally clicking \"Save\".\n\nNow you can display the build badge in your GitHub README file with the following code:\n\n    [![Build Status](https://philipmjohnson.ci.cloudbees.com/buildStatus/icon?job=play-example-quality-assurance)](https://philipmjohnson.ci.cloudbees.com/job/play-example-quality-assurance/)\n\nOf course, replace \"philipmjohnson\" and \"play-example-quality-assurance\" by your own account and job name.\n\nBut, we're getting a little ahead of ourselves, since that's done on a per-repo basis. There's just one more \"one time configuration\" task to do. \n\nOTC Step 4: Tell GitHub your CloudBees public key\n-------------------------------------------------\n\nIn order for the CloudBees Jenkins server to obtain your GitHub project via git, GitHub needs\nto be given your CloudBees public key. Follow the instructions [here](http://wiki.cloudbees.com/bin/view/DEV/How+to+use+Private+GitHub+Repositories+with+CloudBees). \nThough these instructions say they are necessary for private GitHub repositories, actually you need\nto do this even if your repository is public.  In brief:\n  1. In CloudBees, go to Jenkins, then click on \"Manage Jenkins\", then click on \"Configure System\".  In the \"CloudBees DEV@Cloud Authorization\" section, there is a field named \"CloudBees Public Key\". Copy the contents of that field.   \n  2. In GitHub, go to Account Settings, click on \"SSH Keys\", then click \"Add SSH Key\", then paste your CloudBees public key and name it something like \"CloudBees\".\n\nWhen you're done, your GitHub SSH Key page should look something like this:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/github-public-keys.png\"/\u003e\n\nPer Project Configuration\n=========================\n\nNow that you've finished the global configuration of CloudBees and GitHub, we can now \nset up continuous integration process for a specific Play application. Let's call this \n\"per project configuration\" (PPC).\n\nPPC Step 1:  Prime the CloudBees pipeline\n-----------------------------------------\n\n**PPC Step 1.1: Create the default project**\n\nAssume you have a GitHub-hosted Play application called \"play-example-continuous-integration\" for \nwhich you want to set up continuous integration on CloudBees. The\nfirst step is to use the Play ClickStart feature on CloudBees to, in a sense, \"prime the pump\" by\ncreating a sample project also called play-example-continuous-integration. When finished, CloudBees\nwill indicate that it has set up a git repository, jenkins job, mysql database, and running application:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/clickstart-play-example-continuous-integration.png\"/\u003e\n\n**PPC Step 1.2: Delete the git repo on CloudBees**\n\nSince we are using GitHub as our repository, we will not need the one created by ClickStart on \nCloudBees, so it will reduce confusion to delete it.  After dismissing this dialog box, click on \"Repositories\" in the CloudBees nav bar, \nthen select \"play-example-continuous-integration\", then click \"Delete repository\".\n\nPPC Step 2: Make CloudBees Jenkins job point to GitHub repo\n-----------------------------------------------------------\n\nClick on \"Builds\" in the CloudBees nav bar, then select the play-example-continuous-integration job\nto get the following window:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/jenkins-play-example-continuous-integration.png\"/\u003e\n\nIf you are not seeing all the menu items on the left hand side, it is likely because CloudBees\nis displaying you as a \"guest\" user.  If so, click on \"Login\" on the upper right side to restore\nfull access to the job.\n\n**PPC Step 2.1: Wipe out workspace**\n\nI have had problems in the past that were resolved by deleting the default workspace, so I recommend\nthat you click on Workspace, then \"Wipe out workspace\" to get rid of the default project source files. The \nfollowing image shows the project just before clicking the \"Wipe out workspace\" button:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/jenkins-play-example-continuous-integration.png\"/\u003e\n\n**PPC Step 2.2: Point Jenkins job at GitHub repo**\n\nNow we'll tell the Jenkins job where the real source code lives.   Go to your GitHub project and \nfind the \"SSH Clone URL\" text field on the right side of the page, as shown below:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/github-ssh-clone-url.png\"/\u003e\n\nClick the clipboard button to copy the URL. Now go to your CloudBees Jenkins job for \nplay-example-continuous-integration, click on \"Configure\", and scroll down to the source code management section.  You should see something like the following:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/jenkins-source-code-management-1.png\"/\u003e\n\nJenkins is displaying this error because we previously deleted the default repo on CloudBees.\n\nNow paste in the SSH Clone URL that we copied from the GitHub repo, and tab out of the field. Jenkins\nshould now display the following:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/jenkins-source-code-management-2.png\"/\u003e\n\nClick \"Save\" to save the new repo setting to your Jenkins job configuration.\n\nIf Jenkins displays an error, you'll need to fix it. A common problem is forgetting to give\nGitHub your CloudBees public key; see \"OTC Step 4\" for details.\n\nPPC Step 3: Configure build trigger\n-----------------------------------\n\nTo automate continuous integration, we want CloudBees to kick off a build each time a change is \npushed to the GitHub repo.  This requires configuration to both CloudBees and Github.\n\n**PPC Step 3.1: Set Jenkins job to build after a change to GitHub**\n\nSelect \"Configure\" in your job's home page, then scroll down to the \"Build Triggers\" section.\nUnselect \"Build when a change is pushed to CloudBees forge\", and select \"Build when a change is\npushed to GitHub\". The section should now look like this:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/build-triggers.png\"/\u003e\n\nClick \"Save\" to save the new build triggers setting.\n\n**PPC Step 3B: Add a webhook to your GitHub repo**\n\nNow go to your GitHub repository, and click on \"Settings\", then \"Service Hooks\", then \"Webhook URLs\".\nAdd this webhook URL:\n\n    https://philipmjohnson.ci.cloudbees.com/github-webhook/\n    \nReplace \"philipmjohnson\" with your own CloudBees account name.  Click \"Update Settings\". When done,\nit should look like this:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/webhook-url.png\"/\u003e\n\nPPC Step 4: Test your continuous integration and deployment\n-----------------------------------------------------------\n\nYou can now test your new CI and deployment setup.   Simply click on \"Test Hook\" on the Webhook URL page of your \nGitHub repo.  You will not get any output from pressing this button, but it should trigger a new build in CloudBees. \n\nTo see if the build was triggered, go back to your CloudBees Jenkins job main page.  Within 10 seconds or so,\nyou should start to see activity in the Build History window.  See below for the start of the new build:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/first-build-main-page.png\"/\u003e\n\nOnce you see build activity, go to the Console window to watch the progress of the first build:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/console-output-1.png\"/\u003e\n\nIf all goes according to plan, after 5 to 10 minutes the console window should conclude with a \nsuccessful build and deployment:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/console-output-2.png\"/\u003e\n\nCongratulations!  You've just set up continuous integration.  As an added bonus, your application\nhas been automatically deployed to the CloudBees runtime environment and you can play with it there.\n\nPPC Step 5: Automate quality assurance tool invocation (optional)\n-----------------------------------------------------------------\n\nOverall, there are three steps to implementing QA into your continuous integration process:\n\n  1.  Add QA tool invocation to your Play build process, so, for example, you can run \"play checkstyle\" to \n      run the Checkstyle QA tool. For instructions on how do this, see the \n      [play-example-quality-assurance](http://ics-software-engineering.github.io/play-example-quality-assurance/) project.\n      \n  2.  Add the QA tool reporting plugins to your Jenkins instance, as explained in OTC Step 3.2 above.\n  \n  3.  Modify your Jenkins configuration to (a) invoke QA tools in the build command, and (b) \n      invoke QA reporting tools after the build. \n\n\nThis section explains how to do (3).\n\n**PPC Step 5.1: Invoke QA tools in the build command**  \n\nTo invoke your quality assurance tools as part of the build, include them in the build command.\nHere is an example of adding checkstyle, pmd, findbugs, and jacoco:cover to the build command, \nlocated in the \"Build\" section of your Jenkins job configuration page:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/build-command.png\"/\u003e\n\nClick \"Save\" to save this change to your configuration.   Then, click \"Build Now\" to test that\nyour commands run correctly within Jenkins.\n\n**PPC Step 5.2: Invoke QA reporting tools after the build**\n\nTo obtain reports of your QA tool results within Jenkins, you can add \"Post-build Actions\".  In the\nPost-build Actions section of your Jenkins job configuration page, click on \"Add post-build action\". \nIf you have installed the QA plugins correctly, a menu similar to the following should appear:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/post-build-action-menu.png\"/\u003e\n\nSelect the QA tools for which you wish to generate reports.  Here is an example set of post-build actions\nfor Checkstyle, PMD, and FindBugs reporting.  Note that you may need to set the path to the report \ngenerated by the tool invocation.  If you're not sure where the report is located, you can use the\n\"Workspace\" link to search through the target directory.  Note that you may need to configure the QA tool to generate its report in XML format.\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/post-build-actions.png\"/\u003e\n\nHere is an example configuration for Jacoco test coverage reporting:\n\n\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/jacoco-report-config.png\"/\u003e\n\nClick on the \"Advanced\" button to configure aspects of the report. For example, you can configure the \nbuild to fail if a threshold number of warnings are exceeded, or configure the way the graphs are presented\non the page. \n\nSimplifying the setup once you've done it once\n------------------------------------------------\n\nHere's the silver lining for this whole complicated process:  After you've successfully got one of your projects\nconfigured for continuous integration, getting the second one is vastly more simple.   In brief:\n\n  * Use ClickStart to create the new project on CloudBees\n  * Delete the CloudBees repository and Jenkins job.\n  * Create a new Jenkins job, using the \"Copy existing job\" option and selecting a job already setup for CI.\n  * Edit the repository URL and application name.\n  * Add the webhook to your GitHub repo.\n  * Click \"Test hook\" in GitHub to kick off the new build.\n  \nHere's a screencast that goes over these steps in detail:\n\n[\u003cimg src=\"https://raw.github.com/ics-software-engineering/play-example-continuous-integration/master/images/youtube-continuous-integration.png\" width=\"400\"\u003e](https://www.youtube.com/watch?v=8AFC3gn_ZF0)\n\n\nBuild Status\n------------\n\nFor illustration purposes, here's the build status of this project:\n\n [![Build Status](https://philipmjohnson.ci.cloudbees.com/buildStatus/icon?job=play-example-continuous-integration)](https://philipmjohnson.ci.cloudbees.com/job/play-example-continuous-integration/)\n \nAcknowledgements\n----------------\n\nMany thanks to Felix Belzunce of CloudBees who patiently and promptly answered my many questions\nas I developed this tutorial.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fics-software-engineering%2Fplay-example-continuous-integration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fics-software-engineering%2Fplay-example-continuous-integration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fics-software-engineering%2Fplay-example-continuous-integration/lists"}