Change Details

* Our build system is Jenkins and hosted at https://jenkins.c4science.ch * Phabricator also includes support for CircleCI WARNING: Our Jenkins instance has been discontinued. The project will be reactivated at some point, get in touch with us if you are interested ## How to do Continuous Integration (CI) There are two ways of doing unit testing in c4science * [[https://c4science.ch/w/c4science/unit_tests/#using-arcanist-on-your-l|With Arcanist when doing code review or manually (simple)]] * [[https://c4science.ch/w/c4science/unit_tests/#using-jenkins-and-harbor|With Jenkins or external build system (expert)]] ### 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`) ### Using Jenkins and Harbormaster on c4science 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} NOTE: This is a hack and potentially gives access to other users to your build plan. Only use Jenkins for public projects for now * 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 * Phabricator also includes support for CircleCI WARNING: Our Jenkins instance has been discontinued. The project will be reactivated at some point, get in touch with us if you are interested ## How to do Continuous Integration (CI) There are two ways of doing unit testing in c4science * [[#using-jenkins-on-c4science | 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. You can find basic example in this repo: rPHJENKINS ### 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 WARNING: Our Jenkins instance has been discontinued. The project will be reactivated at some point, get in touch with us if you are interested ## How to do Continuous Integration (CI) There are two ways of doing unit testing in c4science * [[https://c4science.ch/w/c4science/unit_tests/#using-arcanist-on-your-l|With Arcanist when doing code review or manually (simple)]] * [[https://c4science.ch/w/c4science/unit_tests/#using-jenkins-and-harbor|With Jenkins or external build system (expert)]] ### 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`) ### Using Jenkins and Harbormaster on c4science 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} NOTE: This is a hack and potentially gives access to other users to your build plan. Only use Jenkins for public projects for now * 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}* [[#using-jenkins-on-c4science | 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. You can find basic example in this repo: rPHJENKINS ### 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`)