* Our build system is Jenkins and hosted at https://jenkins.c4science.ch * Phabricator also includes support for CircleCI NOTE: Jenkins only works for public repositories for now (Credentials are global), we're working on it ## How to do continuous integration Here are the step that you have to setup, detailed in the following sections. * Create a Jenkins Job with parameters * Create a Build Plan on Harbormaster which will trigger the Job * Create an Herald rule which will trigger the Build Plan ## Create a new Job * Create a new Item of type "Freestyle project", give it a name {F17675} * If you want to trigger the build from Herald on a new Diffusion or Commit: choose "This build is parameterized" and add a new String Parameter with the name PHID {F17669} * Select Git as source code management and put the URL of the repository ** If your repository is private, you have to create a new Creadential for it, for instance using an SSH key with your Phabricator username, You'll add the public key to your phabricator profile: https://c4science.ch/settings/panel/ssh/ {F17663} * If you want to periodically build the project, select the option under Build triggers and use this syntax `H/30 * * * *` to build every 30 mn. See complete documentation about the syntax by clicking on the question mark on the right of the field {F17651} * To run your unit test, add a Build step, select Execute Shell and provide the command to run your tests {F17645} * If you want to specify the docker image, you can choose on by clicking on "Restrict where this project can be run" with the following values ** **ubuntu:trusty** Ubuntu Trusty 14.04.4 LTS x86_64 ** **centos:7** Centos 7.2 x86_64 ** More to come {F17639} * If you want to trigger the build from Phabricator, under Build Triggers, tick "Trigger builds remotely" and create a token. ** The best would be some random string, you can generate one like this on a linux shell: `head -c 16 /dev/urandom | md5sum` * To have the status reported back to Phabricator, add the "Post to Phabricator" post-build step ### Trigger build on commit * You can trigger a build from Phabricator using Harbormaster and Herald applications, either on commit or on differential #### Harbormaster (run build) * Create a Build Plan for your repository, https://c4science.ch/harbormaster/plan/ * You'll have to create a custom policy so yourself can view and edit, as well as the @jenkins user {F46021} * Add a new Build Step of type "Make HTTP Request" {F16204} * Add the following URL, `https://jenkins.c4science.ch/buildByToken/buildWithParameters?PHID=${target.phid}&token=<your token>&job=<your job name>` * Select "GET" on the //HTTP Method// field * Select "Wait For Message" on the //When Complete// field. * Save your step {F16207} #### Herald (Notification and action) * Go to Herald, https://c4science.ch/herald/ * Create a new Rule on Commits of type Object * Put the reference of your object, the repository ID (rXX) or callsign (rCALLSIGN) * Give it a name and select the condition as "Repository is any of <your repository>" * Then select the "Run build plans" action with your newly created Build plan * Save the rule * Now when a commit is pushed on your repository, a build will be generated on your Jenkins job and the result will be reported back to phabricator. * You can access the jenkins job build in the harbormaster build, under artifacts, as shown on this image {F16202, size=full}

* Our build system is Jenkins and hosted at https://jenkins.c4science.ch # How to do Continuous Integration (CI) There are two ways of doing unit testing in c4science * [[#using-jenkins-on-c4scien | With Jenkins or external build system (advanced)]] * [[#using-arcanist-on-your-l | With Arcanist when doing code review or manually (simple)]] # Using Jenkins on c4science ### Access Jenkins on c4science is in private beta mode. You can [[https://c4science.ch/maniphest/task/edit/form/8/?title=Jenkins%20access | ask to have access]]. Once you're given access to the group #jenkins_access you will see a `Jenkins Job` tab on every of your repository and a `Create Jenkins Job`on your Project. ### How this works You can create a new Job from a Project page or from the [[/jobs | Jenkins application]]. You'll have to provide a Project that will be used as Policy for the job. Only the people in the Project will have access to the Job on Jenkins. You also have to provide a branch the Job will use. Once you created the job, a Harbormaster build plan and a Herald commit rule will automatically be created. The Herald rule triggers the Harbormaster build plan on new commit on the Repository/Branch couple. The build plan then call the new Jenkins Job. You can see the status of the job from the Project page and the Repository page, as well as the link to the Jenkins job. ### Jenkinsfile The most important part of the setup is the Jenkinsfile. It is a file that must be present in your repository/branch the job will execute against. This file contains a set of options and command that define your Job. #### Examples - You can find basic example in this repo: rPHJENKINS and discuss about the experience in the [[https://c4science.ch/conpherence/84/|chatroom]] - A very good set of examples can be found in the rMUSPECTRE repository https://c4science.ch/source/muSpectre/browse/master/Jenkinsfile : ReadTheDocs trigger, gcc warnings, diffusion interaction (build result posted back to c4science), Jenkins artifacts referenced in the Harbormaster build, ... # Using Arcanist on your local machine We'll be using a community extensions to integrate your custom unit test engine with Phabricator. This extensions allows any [[https://testanything.org/|TAP]] compatible engine to be used. You can also write your own engine, [[https://secure.phabricator.com/book/phabricator/article/arcanist_lint_unit/|take a look at the documentation]]. * In your repository * Add the lib as a submodule ``` git submodule add https://github.com/tagview/arcanist-extensions.git .arcanist-extensions git submodule update --init ``` * Create an `.arcconfig` file with the following content ```{ "load": [ ".arcanist-extensions/tap_test_engine" ], "unit.engine": "TAPTestEngine", "unit.engine.tap.command": "your_unit_test_script.sh" } ``` * Replace `your_unit_test_script.sh` by a script in your repository that do the unit testing and returns the result in a [[https://testanything.org/producers.html|TAP format]] * For instance if your code is in python, you can use `tap.py`, see the example in rPHTEST * Those tests can be run by using the `arc unit` command or it will be run automatically when you create a Differential Revision using Arcanist (`arc diff`)

* Our build system is Jenkins and hosted at https://jenkins.c4science.ch * Phabricator also includes support for CircleCI NOTE: Jenkins only works for public repositories for now (Credentials are global), we're working on it ### How to do cContinuous iIntegration (CI) HThere are the step that you have to setup, detailed in the following sections.e two ways of doing unit testing in c4science * Create a* [[#using-jenkins-on-c4scien | With Jenkins Job with parametersor external build system (advanced)]] * Create a Build Plan on Harbormaster which will trigger the Job * Create an Herald rule which will trigger the Build Plan* [[#using-arcanist-on-your-l | With Arcanist when doing code review or manually (simple)]] # Using Jenkins on c4science ## Create a new Job### Access * Create a new Item of type "Freestyle project",Jenkins on c4science is in private beta mode. You can [[https://c4science.ch/maniphest/task/edit/form/8/?title=Jenkins%20access | ask to have access]]. Once you're given access to the group #jenkins_access give it a name {F17675} * If you want to trigger the build from Herald on a new Diffusion or Commit: choose "This build is parameterized" and add a new String Parameter with the name PHID {F17669} * Select Git as source code management and put the URL of the repository ** If your repository is privateyou will see a `Jenkins Job` tab on every of your repository and a `Create Jenkins Job`on your Project. ### How this works You can create a new Job from a Project page or from the [[/jobs | Jenkins application]]. You'll have to provide a Project that will be used as Policy for the job. Only the people in the Project will have access to the Job on Jenkins. You also have to provide a branch the Job will use. Once you created the job, you have to create a new Creadential for it,a Harbormaster build plan and a Herald commit rule will automatically be created. for instance using an SSH key with your Phabricator username,The Herald rule triggers the Harbormaster build plan on new commit on the Repository/Branch couple. You'll add the public key to your phabricator profile: https://c4science.ch/settings/panel/ssh/ {F17663} * If you want to periodically build the project,The build plan then call the new Jenkins Job. You can see the status of the job from the Project page and the Repository page, as well as the link to the Jenkins job. ### Jenkinsfile The most important part of the setup is the Jenkinsfile. select the option under Build triggers and use this syntax `H/30 * * * *` to build every 30 mnIt is a file that must be present in your repository/branch the job will execute against. See complete documentation about the syntax by clicking on the question mark on the right of the field {F17651} * To run your unit testThis file contains a set of options and command that define your Job. #### Examples - You can find basic example in this repo: rPHJENKINS and discuss about the experience in the [[https://c4science.ch/conpherence/84/|chatroom]] - A very good set of examples can be found in the rMUSPECTRE repository https://c4science.ch/source/muSpectre/browse/master/Jenkinsfile : ReadTheDocs trigger, gcc warnings, diffusion interaction (build result posted back to c4science), add a Build stepJenkins artifacts referenced in the Harbormaster build, select Execute Shell and provide the command to run your tests {F17645} * If you want to specify the docker image,... # Using Arcanist on your local machine We'll be using a community extensions to integrate your custom unit test engine with Phabricator. you can choose on by clicking on "Restrict where this project can be run" with the following values ** **ubuntu:trusty** Ubuntu Trusty 14.04.4 LTS x86_64 ** **centos:7** Centos 7.2 x86_64 ** More to comeThis extensions allows any [[https://testanything.org/|TAP]] compatible engine to be used. You can also write your own engine, [[https://secure.phabricator.com/book/phabricator/article/arcanist_lint_unit/|take a look at the documentation]]. * In your repository {F17639}* Add the lib as a submodule * If you want to trigger the build from Phabricator, under Build Triggers, tick "Trigger builds remotely" and create a token.``` ** The best would be some random string, you can generate one like this on a linux shell: `head -c 16 /dev/urandom | md5sum`git submodule add https://github.com/tagview/arcanist-extensions.git .arcanist-extensions * To have the status reported back to Phabricator, add the "Post to Phabricator" post-build step ### Trigger build on commit * You can trigger a build from Phabricator using Harbormaster and Herald applications, either on commit or on differential #### Harbormaster (run build)git submodule update --init ``` * Create a Build Plan for your repository, https://c4science.ch/harbormaster/plan/n `.arcconfig` file with the following content * You'll have to create a custom policy so yourself can view and edit, as well as the @jenkins user```{ {F46021} * Add a new Build Step of type "Make HTTP Request" {F16204} * Add the following URL, `https://jenkins.c4science.ch/buildByToken/buildWithParameters?PHID=${target.phid}&token=<your token>&job=<your job name>` "load": [ * Select "GET" on the //HTTP Method// field * Select "Wait For Message" on the //When Complete// field. ".arcanist-extensions/tap_test_engine" * Save your step {F16207} #### Herald (Notification and action) ], * Go to Herald, https://c4science.ch/herald/ * Create a new Rule on Commits of type Object "unit.engine": "TAPTestEngine", * Put the reference of your object, the repository ID (rXX) or callsign (rCALLSIGN) * Give it a name and select the condition as "Repository is any of <your repository> "unit.engine.tap.command": "your_unit_test_script.sh" * Then select the "Run build plans" action with your newly created Build plan} * Save the rule``` * Now when a commit is pushed on your repository, a build will be generated on your Jenkins job and the result will be reported back to phabricator.Replace `your_unit_test_script.sh` by a script in your repository that do the unit testing and returns the result in a [[https://testanything.org/producers.html|TAP format]] * You can access the jenkins job build* For instance if your code is in the harbormaster buildpython, under artifactsyou can use `tap.py`, as shown on this imagesee the example in rPHTEST {F16202, size=full}* Those tests can be run by using the `arc unit` command or it will be run automatically when you create a Differential Revision using Arcanist (`arc diff`)