| <!--- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <html> |
| <head> |
| <meta charset="utf-8"> |
| <title>Apache Yetus</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content=""> |
| <meta name="author" content=""> |
| |
| <link href="../../../../assets/css/bootstrap.css" rel="stylesheet"> |
| <link href="../../../../assets/css/bootstrap-theme.css" rel="stylesheet"> |
| <link href="../../../../assets/css/font-awesome.css" rel="stylesheet"> |
| |
| <!-- JS --> |
| <script type="text/javascript" src="../../../../assets/js/jquery-2.1.4.min.js"></script> |
| <script type="text/javascript" src="../../../../assets/js/bootstrap.js"></script> |
| </head> |
| <body> |
| |
| <div class="navbar navbar-inverse navbar-static-top" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="img-responsive pull-left" href="/"> |
| <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" /> |
| </a> |
| </div> |
| <div class="navbar-collapse collapse"> |
| <ul class="nav navbar-nav"> |
| <li><a href="/downloads/">Downloads</a> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li> |
| <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li> |
| <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li> |
| <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a> |
| </li> |
| <li><a href="/documentation/history/">History of the Project</a> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu" aria-labelledby="drop1"> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="https://www.apache.org">Apache Homepage</a> |
| </li> |
| <li><a href="https://www.apache.org/licenses/">Apache License</a> |
| </li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| </li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| <li><a href="https://www.apache.org/security/">Security</a> |
| </li> |
| </ul> |
| </li> |
| </li> |
| </ul> |
| </div> |
| <!--/.nav-collapse --> |
| </div> |
| </div> |
| |
| <div class="container"> |
| <!--- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <h1 id="overview">Overview</h1> |
| |
| <!-- MarkdownTOC levels="1,2" autolink="true" indent=" " bullets="*" bracket="round" --> |
| |
| <ul> |
| <li><a href="#project-specifc-builds">Project-Specifc Builds</a></li> |
| <li><a href="#jenkins-job-tokens">Jenkins Job Tokens</a></li> |
| </ul> |
| |
| <!-- /MarkdownTOC --> |
| |
| <p>The jenkins-admin script is an automated way to submit JIRA issues to the Apache Yetus precommit testing framework. It works by:</p> |
| |
| <ul> |
| <li>Grab the XML output of a JIRA filter that contains all the issues that should be tested by the system. In general, the filter should comprise issues from relevant JIRA projects that are currently in Patch Available state.</li> |
| <li>Process the XML into a list of <code><project-issue>, <attachment id></code> pairs, where attachment id is the id for the <em>newest</em> attachment on the issue. Pulling the newest attachment implies that if multiple attachments are uploaded to an issue, the last one is the one that will be processed and other attachments will be <em>ignored</em>.</li> |
| <li>Grab the single build artifact that this job keeps, <code>patch_tested.txt</code>. This file contains the list of <code><project-issue>, <attachment id></code> pairs that have already been submitted for testing.</li> |
| <li>For each pair from the processed XML, see if the pair is in <code>patch_tested.txt</code>. If not, start a new project build and append the pair to the file.</li> |
| <li>When this admin job completes, archive the latest <code>patch_tested.txt</code> file.</li> |
| </ul> |
| |
| <p>All communication to Jenkins is currently done with the Remote Access API using tokens where necessary (see below). JIRA communication is currently unauthenticated.</p> |
| |
| <p>The JIRA filter is a required value provided via the <code>--jira-filter</code> parameter. It should be the full URL as provided by the JIRA UI.</p> |
| |
| <p>In order to prevent accidents, the <code>--live</code> parameter is required when jenkins-admin is used for production purposes. Without this flag, jobs are not launched but the <code>patch_tested.txt</code> file is created/updated.</p> |
| |
| <p>By default, jenkins-admin expects that the <code>JOB_NAME</code> environment variable will be set by Jenkins. If it is not or it needs to be overridden, that can be done with the <code>--jenkins-jobname</code> parameter.</p> |
| |
| <p>Additionally, the URL of the Jenkins server is expected to be in the <code>JENKINS_URL</code> environment variable, also usually set by Jenkins. This value may be overridden with the <code>--jenkins-url</code> option.</p> |
| |
| <p>The very first run of the job should be done with the <code>--initialize</code> parameter to create the first <code>patch_tested.txt</code> file. Otherwise, the job will fail because a previous version of it cannot be downloaded from previous runs.</p> |
| |
| <h1 id="project-specifc-builds">Project-Specifc Builds</h1> |
| |
| <p>New builds are started via buildWithParameters call. Three parameters are added to the URL:</p> |
| |
| <ul> |
| <li>token = Jenkins security token (see below)</li> |
| <li>ISSUE_NUM = JIRA issue number</li> |
| <li>ATTACHMENT_ID = JIRA attachment id</li> |
| </ul> |
| |
| <p>By default, the Jenkins job name is expected to be <code>PreCommit-{project}</code>, 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:</p> |
| |
| <p>{JENKINS_URL}/job/PreCommit-YETUS/buildWithParameters?token=YETUS-token&ISSUE_NUM=1&ATTACHMENT_ID=2345</p> |
| |
| <p>The <code>{JENKINS_URL}</code> can be overridden on a per project basis using the <code>--jenkins-url-override</code> option. This parameter allows for one job on one Jenkins server to direct different projects to different Jenkins servers. For example:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code> jenkins-admin <span class="nt">--jenkins-url-override</span><span class="o">=</span><span class="nv">PROJ1</span><span class="o">=</span>https://example.com/1 <span class="nt">--jenkins-url-override</span><span class="o">=</span><span class="nv">PROJ2</span><span class="o">=</span>https://example.com/1 |
| </code></pre></div> |
| <p>would send all PROJ1 Jenkins jobs to the first URL and all PROJ2 jobs to the second URL. The <code>--jenkins-url-override</code> option may be listed as many times as necessary.</p> |
| |
| <p>The job name can be overridden via the <code>--jenkins-project-template</code> option. For example, using <code>--jenkins-project-template='{project}-Build'</code>would change the above URL to be:</p> |
| |
| <p>…/job/PreCommit-YETUS-Build/buildwithParameters?…</p> |
| |
| <h1 id="jenkins-job-tokens">Jenkins Job Tokens</h1> |
| |
| <p>Currently, jenkins-admin supports the usage of Jenkins tokens for authentication via the <code>--jenkins-token</code> option. This option provides two ways to do tokens</p> |
| |
| <ul> |
| <li>Flat tokens</li> |
| <li>Template tokens</li> |
| </ul> |
| |
| <p>Flat tokens are a simple string. For example, <code>--jenkins-tokens=yetus</code> would require the <code>yetus</code> string to be listed as the token in the Jenkins job configuration that is being requested.</p> |
| |
| <p>On the other hand, template tokens perform some simple string substitution before being used. This exchange includes:</p> |
| |
| <ul> |
| <li>{project} for the JIRA project name</li> |
| <li>{issue} for the JIRA issue number</li> |
| <li>{attachment} for the JIRA issue attachment id</li> |
| </ul> |
| |
| <p>For example, if JIRA issue YETUS-1 has an attachment of 2345, then <code>{project}</code> becomes <code>YETUS</code>, <code>{issue}</code> becomes <code>1</code>, and <code>{attachment}</code> becomes 2345.</p> |
| |
| <p>By default, the token is set to <code>{project}-token</code>. The token then becomes <code>YETUS-token</code> using the above values.</p> |
| |
| </div> |
| |
| <div class="container"> |
| <hr> |
| <footer class="footer"> |
| <div class="row-fluid"> |
| <div class="span12 text-left"> |
| <div class="span12"> |
| Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation. |
| </div> |
| </div> |
| |
| </div> |
| |
| </footer> |
| </div> |
| |
| </body> |
| </html> |
