Mar 2, 2023
-Deprecated: Automating Phabricator Reviews for Pull Requests¶
-Warning
-DO NOT USE The process below has been superseded. Please contact BDE -for more information.
-Introduction¶
-Note
-The process below is not officially supported by BDE. It is actively used by BDE, and maintained on a best -effort basis. No warranty.
-This page outlines a process for automating the creation of -Phabricator code-reviews for bbgithub -pull requests.
-This integration may be useful to teams that are frustrated with github’s current integrated -support for code reviews, but who otherwise do not expect to manage the -workflow for their change sets through Phabricator (BDE, for example, tracks change-set status in DRQS).
-This integration is built on top of a JaaS (Jenkins-as-a-Service) pipeline for a bbgithub -organization (or repository). Athough some useful documentation links for JaaS are provided in the -Prerequisites, this page assumes the reader will follow JaaS documentaton -to configure a JaaS dedicated instance.
-Comparison to Hubricator¶
-Hubricator, which previously provided a github -webhooks for integrating bbgithub -with Phabricator was shutdown in November 2022. -In comparison to hubricator, this automation is much simpler, and serves only to create and update -phabricator code-reviews, keeping them in sync with a bbgithub pull request. This -tooling does not, for example, monitor the state of the pull request or the state of the phabricator review, or -in any way try and keep the two in sync. On the other hand, the created phabricator -reviews will not expire.
-Prerequisites¶
-We assume the following steps have been done:
--
-
Created a role account for Jenkins to use. (See {SSAM<GO>})
--
-
This role account should be:
--
-
- -
able to run the
/opt/bb/bin/arcon a GNRL Linux machine
-have installed the certificates for Phabricator (see notes)
-assigned as a maintainer for the relevant github repositories
-
-
-- -
Created a dedicated jaas instance using -that role account.
-Added a Jenkins job for the bbgithub-org or bbgithub-repo
-
Note that the instructions here use a Jenkins job run on a BLDLNX machine with NFS access. It -should be possible to replicate this environment on a clean VM by bootstrapping the needed packages from dpkg, -but we have not tested such a configuration nor do we have instructions to help create it.
-As an example, you can see BDE’s:
--
-
- -
- -
The Jenkinsfile for bde/bde-docs
-
Notes
--
-
Please reach out the the
Jenkins as a Serviceself-joinable pchat with questions about configuring Jenkins
-To install certificates for the role account, login to a GNRL Linux machine using the role account and run:
arc --install-certificate https://all.phab.dev.bloomberg.com/
-Per the bbgithub bootstrapping steps,
bbgithub:should be configured as a host protocol alias in your ssh configuration (so -for examplebbgithub:bde/bdecan be used to refer to thebde/bderepository).
-
phabricatorbot.py¶
-The BDE tooling for generating phabricator reviews is a python script, -phabricatorbot.py.
-On NFS systems, there is a canonical version (used by BDE’s Jenkins integration) at
-/bb/bde/bbshr/bde-ci-tools/bin/phabricatorbot.py
A command-line example for using this tool is:
-python3.8 /bb/bde/bbshr/bde-ci-tools/bin/phabricatorbot.py \
- --create-checkout /my/checkout/location/PR-4025 \
- --url https://bbgithub.dev.bloomberg.com/bde/bde/pull/4025 \
- --verbose
-The above command will checkout bde/bde pull request 4025 to the directory /my/checkout/location/PR-4025,
-and run arc diff on it.
Once a phabricator review is created, phabricatorbot will update the pull request
-with a comment including the URL for the created phabricator review.
-If phabricatorbot is run multiple times on the same pull request, the script will
-update the previously created Phabricator review (by looking for the old review id
-in the comments of the pull request).
For command line help:
-phabricatorbot.py --help
-Integrating Phabricatorbot Into Jenkins¶
-See the Prerequisites for more on configuring Jenkins. Once the
-webhooks are created for the bbgithub organization or repository, you should create or modify the
-Jenkinsfile for the repository. A skeleton Jenkins file is shown
-here.
Then add a stage for creating a phabricator review from the pull request like the one below:
-stage('Update phabricator with lint'){
- when {
- branch "PR-*" // a stage only runs for pull requests
- }
- steps {
- echo 'running arc diff on pull request'
- sh """
- /opt/bb/bin/python3.8 /bb/bde/bbshr/bde-ci-tools/bin/phabricatorbot.py --verbose --create-checkout ${WORKSPACE} --url ${CHANGE_URL}
- """
- }
- }
-}
-Here is an example Jenkinsfile for the bde-docs repo.
-Important Environment Variables
-The command line supplied to phabricatorbot.py uses the following variables, which are automatically available in the Jenkins shell environment:
-
-
${CHANGE_URL}contains the pull requests URL
-${WORKSPACE}is the workspace directory Jenkins expects to use
-
Configuring the Git Checkout¶
-The Jenkins pipeline for creating a Phabricator review needs to checkout the pull-request to
-generate a code review. This can either be done by using the --create-checkout option to phabricatorbot
-(as shown in the example above), or with the Jenkin’s command checkout scm.
Note
-If you do not use the Jenkins pipeline to perform test builds, you should prefer the phabricatorbot --create-checkout
-option (as seen in the example above) to Jenkin’s checkout scm
Unfortuantely, the Jenkins command checkout scm performs a checkout that is not always suitable for arc diff 1.
-If you need to use checkout scm to perform a test build, do not pass the --create-checkout option to
-phabricatorbot. Without the --create-checkout option, phabricatorbot will assume there is a checked out
-version of the repository in the current working directory. phabricatorbot will stash the commit id for the
-current working directory, checkout out the pull request, run arc diff, and then restore the stashed commit id as HEAD.
-This extra complexity is unnecessary if the checkout in not needed for a test build.
-
-
- 1 -
The result of
-checkout scmincludes a merge-commit back to the target branch -that can result in a confused phabricator code-review
-
Contact¶
-For additional information, please contact Henry Verschell or Mike Giroux of the BDE team.
-