Show arbitrary build results
Problem to Solve
It is unrealistic for GitLab CI to natively support every such build result. What is a "build result"? Examples might include code coverage results, test results, output from static analysis tools, generated logs, pages with shortcut links, and more that provide context to contributors about the state of their contribution and/or the overall project.
Intended users
- Delaney (Development Team Lead)
- Sasha (Software Developer)
- Devon (DevOps Engineer)
- Sam (Security Analyst)
Proposal
This is a request to allow arbitrary build results / links to be included in the merge request page. To achieve this we will add a new option to the artifacts:
element that will track these items as being ones to highlight:
custom_output:
script: generator.sh > path/to/report.html
artifacts:
expose_as: 'Generator Output'
paths:
- path/to/report.html
Then, for any jobs that produced outputs where this new element is provided, a new section is added to the latest pipeline section in the MR widget here:
There, any formats supported by the artifact browser (as implemented via https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14399) would be displayed in a new tab, or downloaded if not supported. In this way generated .html or other artifacts can be coordinated and easily linked to. The generated .html could contain important content itself, or be a further list of manually generated links to any other resources.
Use Cases
Single match
test:
script: [ 'echo 1' ]
artifacts:
expose_as: 'see file 1'
paths: ['path/to/file1.html']
This will show a link "see file 1" pointing directly to the file content inside the artifacts browser.
Multiple matches
test:
script: [ 'echo 1' ]
artifacts:
expose_as: 'see artifacts'
paths: ['path/to/file1.txt', 'path/to/file2.txt']
# equivalent:
# paths: ['path/to/directory/']
# paths: ['path/to/directory/*.png']
This will show a link "see artifacts" pointing to the job folder of the artifacts browser (all artifacts for the given job).
Directory match
test:
script: [ 'echo 1']
artifacts:
expose_as: 'artifact 1'
paths: ['path/to/directory/']
If a directory contains 1 file this will point to the exact file path. If a directory contains more files this will point to the job folder in the artifacts browser.
Multiple exposed artifacts across jobs
Limit the total list to 10 for now.
Multiple exposed artifacts on a single job
Link to the job folder in the artifacts browser.
In the future, we can improve this by supporting external things:
Implementation
UI Concept
The solution adds an expandable section to the pipeline section in the merge request widget. It can be featured together with the deployment information but will, in that case, be positioned above it.
It features a counter for the number of exposed artifacts and if expanded will display a table view of exposed artifacts. This table view currently displays the artifact string name, the URL towards the source file, and the job name + link which generated it.
- Artifact links will open up a new tab
- Job links will link directly
All configured exposed artifacts will be visible in a single list. The maximum will be 10
and if more artifacts are exposed the .GitLab-ci.yml will be invalidated.
Collapsed | Expanded |
---|---|
Permissions and Security
Documentation
We will need to document usage of this feature.
Testing
What does success look like, and how can we measure that?
We will measure success of this feature by capturing clicks on the arbitrary items from the list.