HTML reports publishing in Jenkins - Deep Dive

Overview - HTML reports publishing

What is it?

HTML reports publishing in Jenkins means showing web pages created by your build or test process inside Jenkins. These reports are usually files with charts, tables, or logs that help you understand how your code or tests performed. Jenkins collects these HTML files and makes them easy to view from the Jenkins interface. This helps teams quickly see results without searching through files manually.

Why it matters

Without HTML reports publishing, teams would have to dig through folders or logs to find test results or build summaries. This wastes time and can cause mistakes or missed problems. Publishing HTML reports makes information clear and accessible, speeding up feedback and improving software quality. It turns raw data into easy-to-understand visuals right inside Jenkins.

Where it fits

Before learning HTML reports publishing, you should know basic Jenkins concepts like jobs, builds, and workspace files. After mastering this, you can explore advanced reporting plugins, automated test result analysis, and integrating reports with notifications or dashboards.

Mental Model

Core Idea

HTML reports publishing in Jenkins is like putting a finished project display in a common room where everyone can easily see and understand the results.

Think of it like...

Imagine you bake cookies and want to show your friends how they turned out. Instead of giving them the recipe or ingredients, you put the cookies on a plate in the living room. Everyone can see and taste them easily. Jenkins HTML reports publishing is like placing that plate in a shared space for all to enjoy.

┌─────────────────────────────┐
│ Jenkins Job Workspace        │
│ ┌─────────────────────────┐ │
│ │ HTML Report Files       │ │
│ └─────────────────────────┘ │
│                             │
│  ↓ Publish HTML Reports      │
│                             │
│ ┌─────────────────────────┐ │
│ │ Jenkins UI - Report Tab │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Jenkins Job Workspace

Concept: Learn where Jenkins stores files during a build.

Every Jenkins job has a workspace folder on the build agent machine. This folder holds all files created or used during the build, like source code, compiled programs, and test results. HTML reports are usually generated here as files.

Result

You know where to find the HTML report files after a build finishes.

Understanding the workspace location is key because Jenkins publishes reports from files stored there.

2

Foundation

Generating HTML Reports in Builds

Concept: Learn how build tools create HTML reports.

Many testing or analysis tools produce HTML reports automatically. For example, test frameworks can output results as HTML files with charts and tables. These files are saved in the workspace during the build process.

Result

Your build produces HTML report files ready for publishing.

Knowing how reports are generated helps you prepare Jenkins to find and display them.

3

Intermediate

Configuring Jenkins to Publish HTML Reports

🤔Before reading on: do you think Jenkins needs a plugin or built-in feature to publish HTML reports? Commit to your answer.

Concept: Learn how to tell Jenkins to show HTML reports after a build.

Jenkins uses the 'Publish HTML reports' post-build action. You add this step in your job configuration, specify the folder where HTML files are, and name the report. Jenkins then creates a new tab in the build page to display the report.

Result

After the build, Jenkins shows a clickable tab with your HTML report inside the job page.

Knowing how to configure publishing turns raw files into accessible, visual reports for your team.

4

Intermediate

Handling Multiple HTML Reports in One Job

🤔Before reading on: can Jenkins publish more than one HTML report per job? Commit to yes or no.

Concept: Learn to publish several different HTML reports from the same build.

You can add multiple 'Publish HTML reports' actions in one job. Each action points to a different folder and report name. Jenkins will create separate tabs for each report, letting users switch between them easily.

Result

Your Jenkins build page shows multiple report tabs, each with different HTML content.

Understanding multiple reports lets you organize complex build outputs clearly.

5

Intermediate

Using Relative Paths and Index Files

Concept: Learn how to specify correct paths and main HTML files for reports.

In the publish configuration, you give a relative path from the workspace to the report folder. You also specify the main HTML file (like index.html) Jenkins should open first. This ensures Jenkins loads the right page when users click the report tab.

Result

Jenkins opens the correct HTML page inside the report tab without errors.

Correct paths prevent broken links and missing pages in your published reports.

6

Advanced

Securing HTML Reports from Unsafe Content

🤔Before reading on: do you think Jenkins automatically sanitizes all HTML report content? Commit to yes or no.

Concept: Learn about security risks and how Jenkins handles them.

HTML reports can contain scripts or unsafe content. Jenkins sanitizes some parts but does not fully secure all HTML. You should avoid including untrusted scripts or sensitive data in reports. Plugins may offer options to control sanitization.

Result

You understand the security risks and take steps to keep reports safe.

Knowing security limits prevents exposing your Jenkins server to attacks via reports.

7

Expert

Automating Report Publishing in Pipeline Scripts

🤔Before reading on: can you publish HTML reports in Jenkins Pipeline using code? Commit to yes or no.

Concept: Learn how to publish HTML reports using Jenkins Pipeline syntax.

In Jenkins Pipeline (Jenkinsfile), you use the 'publishHTML' step to publish reports. You specify reportDir, reportFiles, and reportName in the step. This allows full automation and version control of report publishing in code.

Result

Your pipeline automatically publishes HTML reports after builds without manual config.

Automating report publishing in pipelines improves repeatability and reduces manual errors.

Under the Hood

Jenkins stores build files in a workspace directory on the build agent. When configured, the 'Publish HTML reports' feature copies or links the specified HTML files from the workspace to a special Jenkins directory for that build. Jenkins then serves these files through its web interface by embedding them inside an iframe or direct HTML view. It uses relative paths to keep links working and applies basic sanitization to prevent some unsafe content. The UI creates tabs dynamically for each report configured.

Why designed this way?

This design keeps reports tied to specific builds, ensuring historical data is preserved. Serving files from Jenkins avoids manual file sharing or external servers. Using relative paths and iframes allows complex reports with multiple pages and resources to work seamlessly. The plugin approach lets Jenkins remain flexible and lightweight, supporting many report types without bloating core functionality.

┌───────────────┐       ┌─────────────────────┐
│ Build Agent   │       │ Jenkins Master UI   │
│ Workspace    │──────▶│ HTML Report Storage  │
│ (HTML files) │       │ (per build folder)   │
└───────────────┘       └─────────────────────┘
         │                        │
         │                        ▼
         │               ┌───────────────────┐
         │               │ Jenkins Web Server │
         │               │ Serves HTML Reports│
         │               └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Jenkins automatically find and publish all HTML files in the workspace without configuration? Commit yes or no.

Common Belief: Jenkins automatically detects and publishes all HTML reports generated by builds.

Reality: Jenkins only publishes HTML reports if you explicitly configure the 'Publish HTML reports' action or use pipeline steps. It does not auto-discover reports.

Why it matters: Without configuring publishing, reports remain hidden in the workspace, wasting effort and confusing users.

Quick: Can HTML reports include any JavaScript safely in Jenkins? Commit yes or no.

Common Belief: All JavaScript in HTML reports runs safely inside Jenkins without risk.

Reality: Jenkins sanitizes some content but does not guarantee full security. Malicious scripts can pose risks if included in reports.

Why it matters: Ignoring this can expose Jenkins to cross-site scripting attacks or data leaks.

Quick: Can you publish HTML reports from any folder on the build agent? Commit yes or no.

Common Belief: You can publish HTML reports from any folder on the build agent machine.

Reality: Jenkins only publishes reports from the job's workspace or paths accessible within it, not arbitrary folders on the agent.

Why it matters: Trying to publish from outside the workspace causes errors or missing reports.

Quick: Does publishing multiple HTML reports in one job require special plugins? Commit yes or no.

Common Belief: You need special plugins to publish more than one HTML report per Jenkins job.

Reality: The standard 'Publish HTML reports' feature supports multiple reports by adding multiple actions.

Why it matters: Believing otherwise limits report organization and clarity in complex builds.

Expert Zone

1

Jenkins serves HTML reports using iframes, which can cause issues with some modern browser security policies like Content Security Policy (CSP).

2

The relative paths in reports must be carefully managed; absolute paths or external links can break when viewed inside Jenkins UI.

3

Pipeline scripted publishing allows dynamic report paths and names, enabling complex workflows and conditional report generation.

When NOT to use

Avoid using Jenkins HTML report publishing for very large or highly interactive reports that require backend processing or real-time updates. Instead, use dedicated reporting servers or dashboards like Grafana or custom web apps.

Production Patterns

In production, teams integrate HTML report publishing with automated test suites, code coverage tools, and static analysis. Reports are versioned with builds and linked in notifications. Pipelines automate publishing, and multiple reports are combined for comprehensive quality dashboards.

Connections

Continuous Integration

Builds on

Publishing HTML reports is a key part of continuous integration feedback, making build and test results visible immediately.

Web Security

Related concern

Understanding web security helps prevent risks when displaying HTML reports that may contain scripts or sensitive data.

Digital Publishing

Similar pattern

Like digital publishing platforms organize and display content for readers, Jenkins organizes and presents build reports for developers.

Common Pitfalls

#1 Using absolute file paths for report location.

Wrong approach:

Publish HTML reports with /home/jenkins/workspace/job/report/index.html as the report path.

Correct approach:

Publish HTML reports with relative path like report/index.html from the workspace root.

Root cause:

Misunderstanding that Jenkins expects paths relative to the workspace, not absolute system paths.

#2 Not specifying the main HTML file, causing blank report tabs.

Wrong approach:

Configure publish HTML reports with folder but leave 'index page' field empty.

Correct approach:

Specify 'index.html' or the main report file explicitly in the publish HTML reports configuration.

Root cause:

Assuming Jenkins will guess the main file, but it requires explicit input to load the report.

#3 Including unsafe JavaScript in reports without sanitization.

Wrong approach:

Embedding third-party scripts or inline JavaScript in HTML reports without review.

Correct approach:

Avoid or sanitize scripts in reports; use trusted content only.

Root cause:

Lack of awareness about Jenkins' limited sanitization and web security risks.

Key Takeaways

Jenkins HTML reports publishing makes build and test results easy to view inside Jenkins by showing HTML files from the workspace.

You must configure Jenkins explicitly to publish reports, specifying relative paths and main HTML files.

Multiple reports can be published per job, each shown as separate tabs for clarity.

Security is important: avoid unsafe scripts in reports to protect Jenkins from attacks.

Pipeline scripts can automate report publishing, improving repeatability and reducing manual setup.

Practice

1. What is the main purpose of publishing HTML reports in Jenkins?

easy

A. To display test and build results inside Jenkins in a readable format

B. To execute shell commands during the build

C. To send email notifications after a build

D. To create new Jenkins jobs automatically

Solution

1. Step 1: Understand the role of HTML reports in Jenkins

   HTML reports are used to show test and build results in a user-friendly way inside Jenkins.

2. Step 2: Identify the correct purpose

   Among the options, only displaying results inside Jenkins matches the purpose of HTML reports.

3. Final Answer:

   To display test and build results inside Jenkins in a readable format -> Option A

4. Quick Check:

   HTML reports = readable results inside Jenkins [OK]

Hint: HTML reports show results inside Jenkins UI [OK]

Common Mistakes:

• Confusing HTML reports with build execution steps
• Thinking HTML reports send notifications
• Assuming HTML reports create jobs

2. Which of the following is the correct syntax to publish an HTML report in a Jenkins pipeline script?

easy

A. publishHTML { reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report' }

B. publishHTML(reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report')

C. publishHTML('reports', 'index.html', 'My Report')

D. publishHTML(target: [allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report'])

Solution

1. Step 1: Review the correct Jenkins pipeline syntax for publishHTML

   The publishHTML step requires a target map with keys like allowMissing, alwaysLinkToLastBuild, keepAll, reportDir, reportFiles, and reportName.

2. Step 2: Compare options to syntax

   publishHTML(target: [allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report']) correctly uses the target map with all required keys and proper syntax.

3. Final Answer:

   publishHTML(target: [allowMissing: false, alwaysLinkToLastBuild: true, keepAll: true, reportDir: 'reports', reportFiles: 'index.html', reportName: 'My Report']) -> Option D

4. Quick Check:

   publishHTML uses target map syntax [OK]

Hint: Use publishHTML with target map and keys [OK]

Common Mistakes:

• Omitting the target keyword
• Passing parameters as separate arguments
• Using curly braces instead of parentheses

3. Given this Jenkins pipeline snippet:

publishHTML(target: [allowMissing: true, keepAll: false, reportDir: 'test-results', reportFiles: 'summary.html', reportName: 'Test Summary'])

What happens if the 'summary.html' file is missing after the build?

medium

A. The build will fail due to missing report file

B. The build will succeed and no report will be shown

C. Jenkins will create an empty report automatically

D. The build will pause and wait for the file

Solution

1. Step 1: Understand the allowMissing option

   allowMissing: true means Jenkins will not fail the build if the report file is missing.

2. Step 2: Predict behavior when file is missing

   Since allowMissing is true, the build succeeds but no report is shown.

3. Final Answer:

   The build will succeed and no report will be shown -> Option B

4. Quick Check:

   allowMissing true = no failure if missing [OK]

Hint: allowMissing true lets build pass without report [OK]

Common Mistakes:

• Assuming build fails when allowMissing is true
• Thinking Jenkins creates missing files
• Believing build pauses for missing files

4. You configured publishHTML in your Jenkins pipeline but the HTML report does not appear in the build results. Which of these is the most likely cause?

medium

A. The Jenkins server needs a restart

B. The publishHTML step is missing the allowMissing option

C. The reportDir path is incorrect or does not contain the report files

D. The reportName is too long

Solution

1. Step 1: Check common reasons for missing HTML reports

   If the reportDir path is wrong or empty, Jenkins cannot find the report files to display.

2. Step 2: Evaluate other options

   allowMissing missing does not prevent report display if files exist; reportName length and server restart are unrelated.

3. Final Answer:

   The reportDir path is incorrect or does not contain the report files -> Option C

4. Quick Check:

   Wrong reportDir = no report shown [OK]

Hint: Verify reportDir path and files exist [OK]

Common Mistakes:

• Ignoring reportDir correctness
• Thinking allowMissing affects report visibility
• Restarting Jenkins unnecessarily

5. You want Jenkins to keep all HTML reports from every build and always link to the latest report. Which configuration achieves this?

hard

A. publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

B. publishHTML(target: [keepAll: false, alwaysLinkToLastBuild: false, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

C. publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: false, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

D. publishHTML(target: [keepAll: false, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report'])

Solution

1. Step 1: Understand keepAll and alwaysLinkToLastBuild options

   keepAll: true keeps reports from all builds. alwaysLinkToLastBuild: true creates a link to the latest report.

2. Step 2: Match options to requirement

   publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report']) sets both keepAll and alwaysLinkToLastBuild to true, meeting the requirement.

3. Final Answer:

   publishHTML(target: [keepAll: true, alwaysLinkToLastBuild: true, reportDir: 'output', reportFiles: 'report.html', reportName: 'Build Report']) -> Option A

4. Quick Check:

   keepAll and alwaysLinkToLastBuild true = keep all and link latest [OK]

Hint: Set keepAll and alwaysLinkToLastBuild to true [OK]

Common Mistakes:

• Setting keepAll false loses old reports
• Not linking to last build report
• Confusing option names