Allow users to construct a URL pointing to pages of the latest job artefact
Problem to solve
We have no way of constructing an URL to the latest Pages of artefacts created by the latest job of a given %{ref}
and %{job}
. This URL is necessary when we want to point to e.g. the coverage report that computed a given coverage percentage (on a badge), or documentation of a particular tag/branch.
Further details
In Coveralls (a coverage tool), you can build a URL that points to the detailed coverage report of the latest job that computed the coverage percentage:
[![Coverage Status](https://coveralls.io/repos/github/%{project_path}/badge.svg)](https://coveralls.io/github/%{project_path})
This is very helpful because
- percentage of coverage is not as good as the coverage report
- coverage report is typically difficult to find (because it depends on a job, an artefact, etc.)
- we do not want to point to a particular job id, but to the latest job id of a
%{ref}
.
Another example is documentation. In ReadTheDocs, the badge is
[![Documentation Status](https://readthedocs.org/projects/%{project_name}/badge/?version=latest)](https://%{project_name}.readthedocs.io/en/latest/?badge=latest)
When the badge is a summary of a report, the badge typically points to the report itself.
Generally, an artefact created from a given %{ref}
by a job (e.g. coverage report, documentation, a notebook) is expected to be accessible to a certain audience. An important part of that broadcasting is its URL.
The page's URL of an artefact %{path}
produced by a %{job_id}
is given by https://%{namespace}.gitlab.io/-/%{project_name}/-/jobs/%{job_id}/artifacts/%{path}
. This is the canonical URL of that artefact and is great to have.
However, this particular URL is not useful to broadcast the latest version of the artefact of the ref %{ref}
and %{job}
because we cannot construct it out of these two variables.
As per documentation, there is a way to browse the latest artefact of a given %{ref}
and %{job}
:
https://example.com/%{namespace}/%{project}/-/jobs/artifacts/%{ref}/browse?job=%{job}
This redirects to the latest artefact of %{ref}, %{job}
:
https://gitlab.com/%{namespace}/%{project}/-/jobs/%{job_id}/artifacts/browse
However, there is no (documented) URL that redirects to the artefact's Page. I.e. a URL that
given %{ref}
, %{path}
and %{job}
, redirects to
https://%{namespace}.gitlab.io/-/%{project_name}/-/jobs/%{job_id}/artifacts/%{path}
where %{job_id}
is the latest job on (%{ref}, %{job})
.
Proposal
Create a new URL, like the one to browse artefacts, constructed from %{ref}, %{job}, %{path}
, that redirects to the latest respective artifact's page. For example,
https://%{namespace}.gitlab.io/-/%{project_name}/artifacts/%{path}?ref=%{ref}&job=%{job}
which redirects to the respective page:
https://%{namespace}.gitlab.io/-/%{project_name}/-/jobs/%{job_id}/artifacts/%{path}
where %{job_id}
is always the latest job id of the pair (%{ref}, %{job})
.
This solves the problem above because there is a direct relationship between the type of artefact, its version and its html to the above variables:
- type of artefact (e.g. coverage, documentation) <=>
%{job}
- version of artefact (e.g.
master
,v1.0
) <=>%{ref}
- entry point of the artefact in html (e.g.
docs/index.html
) <=>%{path}
With the existence of such URL, the following features become supported:
- badges can have URLs to pages produced by artefacts produced in gitlab (like the coverall and readthedocs above, but using gitlab jobs)
- versioned generated documentation: documentation of tag vX.Y.Z is the url to
%{job},%{ref},%{path}
whereref == vX.Y.Z
. The person can still decide to publish the latest documentation as per this example (usingpublic/
).
What does success look like, and how can we measure that?
- Allow the user to write the following on the
README.md
:
Check the latest documentation at
https://%{namespace}.gitlab.io/-/%{project_name}/artifacts/%{path}?ref=master&job=documentation
and documentation of v1.0.0 athttps://%{namespace}.gitlab.io/-/%{project_name}/artifacts/%{path}?ref=v1.0.0&job=documentation
(replaced by actual text, with text links)
- Allow the user to write the following on the
README.md
(equivalent in the project's Badges):
[![Coverage Status](https://gitlab.com/%{namespace}/%{project_name}/badges/master/coverage.svg?ref=master&job=coverage)](https://%{namespace}.gitlab.io/-/%{project_name}/artifacts/%{path}?ref=master&job=coverage)
Ultimately, this allows the same functionality that would be possible with coverall/readthedocs/external reporting tools, but with the obvious advantage of being integrated with pages, jobs and CI/CD.
Links / references
- Related/improvement of #34102 (closed)