Integration with Jenkins
Universum requires no special integration with Jenkins, except for one thing. It is usually launched as one long step in a single build stage. Because of that, the whole Universum log is printed as a plain text without navigation anchors.
Compare with these:
When ran locally, all Universum build step logs are stored to separate files instead of printing their output to console
When launched by TeamCity, Unviersum uses service messages to increase log readability
To simplify navigating long logs and finding relevant information on build results, we provide a user-friendly interactive log with collapsible blocks and other features. This log can also be used outside of Jenkins, but for Jenkins users it adds the missing functionality.
Warning
By default, Jenkins does not render interactive content. This means that without changing server settings, interactive features of the generated log will be inaccessible when opened directly from Jenkins artifacts.
Here’s the list of steps we performed to integrate the interactive log with Jenkins server:
Add a command line option to generate a self-contained HTML file
Add a Jenkins plugin to integrate a generated log into a Jenkins job
Set up Resource Root URL to allow Jenkins rendering interactive content
Configure reverse proxy to handle multiple domains interaction
Add command line option
To generate a single interactive self-contained HTML file, pass an –html-log option to command line. It will be stored to in project artifacts folder. Note that the log name can either be specified or left default.
Note
Jenkins jobs do not show any files via web interface if not not specifically configured to do so. Use
archiveArtifacts
in Pipeline or Archive the artifacts
in Post-build Actions to check the file presence
and contents before next step if needed
Add a Jenkins plugin
A HTML Publisher plugin is a very convenient way to add an HTML report to a Jenkins job. To use it, you will need to:
Install it on server (server restart might be needed to apply changes)
Pass the generated log name to plugin configuration as described in manual (https://plugins.jenkins.io/htmlpublisher/) via Post-build Actions or Pipeline
Launch a configured job at least once for the log to be generated
Let Jenkins render the interactive content of log (see the next section)
Set up Resource Root URL
As already mentioned above, due to Jenkins Content-Security-Policy some features of an interactive log might not work properly, and its contents might be displayed incorrectly.
A recommended way to allow Jenkins server to render interactive user content is to configure Jenkins to publish
artifacts on a different domain
by changing Resource Root URL
in Manage Jenkins » Configure System » Serve resource files from another domain
from <main domain>
to <resource domain>
(e.g. my.jenkins.io
to res.my.jenkins.io
).
Note that Jenkins interaction with resource domain, resolved to the same host IP is not done via localhost
network interface. The reason for that is Jenkins requiring some interaction with itself via this domain name.
This means that both <main domain>
and <resource domain>
domain names must be resolved correctly, either
globally (via DNS) or locally on both client and server machines (via /etc/hosts
files). The correctness of
name resolving is checked when saving the changes to this setting; but Jenkins will only show warning, and not
fail if domain name is not resolved.
Note
If main server domain name is not resolved using DNS, /etc/hosts
or any other means, the web-interface
will only be accessible via IP, and not the name. Because of that, the Jenkins interaction with itself
via domain name will fail because host name is not passed to the Jenkins server
Here are the symptoms of domain names not resolving correctly:
Jenkins warnings when trying to save the updated settings
Client inability to access said pages (timeout error)
To set up domain name resolving, add following lines to server /ets/hosts
file:
127.0.0.1 <main domain>
<server IP> <resource domain>
And add the following lines to client /ets/hosts
file:
<server IP> <main domain>
<server IP> <resource domain>
Configure reverse proxy
Note that this step is only needed if Nginx reverse proxy is used.
To understand why these fixes are needed, let’s pay more attention to the mechanism of ‘another domain’, used by Jenkins. When requesting an artifact, that is served from another domain, user first goes to main Jenkins web server, that returns a redirection link to acquire a said artifact.
As specified in docs,
without specification Nginx replaces Host
header with $proxy_host
. In this case it changes
<resource domain>
to proxy IP specifications. The problem is that without the Host header the Jenkins server
is not able to understand that the request is sent to the resource domain. Therefore it returns the 404 NOT FOUND error.
To pass them correctly, adjust the configuration as instructed in manual mentioned above. Add the following lines to Nginx configuration file:
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
so that real headers are passed to Jenkins to handle the resource domain magic.
Note
Also you might need to set server_name
to <main domain> <resource domain>
(whitespace separated)