Overview

The jenkins-admin script is an automated way to submit JIRA issues to the Apache Yetus precommit testing framework. It works by:

All communication to Jenkins is currently done with the Remote Access API using tokens where necessary (see below). JIRA communication is currently unauthenticated.

The JIRA filter is a required value provided via the --jira-filter parameter. It should be the full URL as provided by the JIRA UI.

In order to prevent accidents, the --live parameter is required when jenkins-admin is used for production purposes. Without this flag, jobs are not launched but the patch_tested.txt file is created/updated.

By default, jenkins-admin expects that the JOB_NAME environment variable will be set by Jenkins. If it is not or it needs to be overridden, that can be done with the --jenkins-jobname parameter.

Additionally, the URL of the Jenkins server is expected to be in the JENKINS_URL environment variable, also usually set by Jenkins. This value may be overridden with the --jenkins-url option.

The very first run of the job should be done with the --initialize parameter to create the first patch_tested.txt file. Otherwise, the job will fail because a previous version of it cannot be downloaded from previous runs.

Project-Specifc Builds

New builds are started via buildWithParameters call. Three parameters are added to the URL:

By default, the Jenkins job name is expected to be PreCommit-{project}, where the project name matches the JIRA project name. Using the JIRA issue YETUS-1 with an attachment number of 2345 would result in the following URL:

{JENKINS_URL}/job/PreCommit-YETUS/buildWithParameters?token=YETUS-token&ISSUE_NUM=1&ATTACHMENT_ID=2345

The {JENKINS_URL} can be overridden on a per project basis using the --jenkins-url-override option. This parameter allows for one job on one Jenkins server to direct different projects to different Jenkins servers. For example:

   jenkins-admin --jenkins-url-override=PROJ1=https://example.com/1 --jenkins-url-override=PROJ2=https://example.com/1

would send all PROJ1 Jenkins jobs to the first URL and all PROJ2 jobs to the second URL. The --jenkins-url-override option may be listed as many times as necessary.

The job name can be overridden via the --jenkins-project-template option. For example, using --jenkins-project-template='{project}-Build'would change the above URL to be:

…/job/PreCommit-YETUS-Build/buildwithParameters?…

Jenkins Job Tokens

Currently, jenkins-admin supports the usage of Jenkins tokens for authentication via the --jenkins-token option. This option provides two ways to do tokens

Flat tokens are a simple string. For example, --jenkins-tokens=yetus would require the yetus string to be listed as the token in the Jenkins job configuration that is being requested.

On the other hand, template tokens perform some simple string substitution before being used. This exchange includes:

For example, if JIRA issue YETUS-1 has an attachment of 2345, then {project} becomes YETUS, {issue} becomes 1, and {attachment} becomes 2345.

By default, the token is set to {project}-token. The token then becomes YETUS-token using the above values.