ui-ci: add a "ci" tab which redirects to an external ci system

Add a "ci" page which redirects to an external ci system for the ref
being viewed, along with a tab for it in the repository header.

The target is a url template, configurable globally or per repository,
with separate settings for branches and tags because pipelines for the
two commonly live at different locations: on a Jenkins multibranch
pipeline a branch is at job/<name>/job/<ref> while a tag is at
job/<name>/view/tags/job/<ref>. $ref, $repo and $slug are substituted,
$slug being the repository url with any ".git" suffix removed and slashes
replaced by dashes, which is the shape job names usually take.

An explicit repo.ci-url drops the branch and tag urls the repository
would otherwise inherit from the global settings, as it could never take
effect otherwise.

The expansion is written to the Location header verbatim rather than
through cgit_redirect(), which percent-encodes '?', '=' and '%' and would
corrupt any url carrying a query string. An expansion containing CR or LF
is refused so that it cannot smuggle in further headers.

Signed-off-by: Saya Andy <saya.andy@posteo.com>

1 files changed, 70 insertions, 0 deletions

diff --git a/cgitrc.5.txt b/cgitrc.5.txt
index 7c39bf9..145a17e 100644
--- a/cgitrc.5.txt
+++ b/cgitrc.5.txt
@@ -100,6 +100,23 @@ cache-static-ttl::
 	version of repository pages accessed with a fixed SHA1. See also:
 	"CACHE". Default value: -1".
 
+ci-branch-url::
+	Url template used by the "ci" tab when a branch is being viewed. If
+	unspecified, `ci-url` is used instead. Default value: none. See also:
+	"CI URL EXPANSION".
+
+ci-tag-url::
+	Url template used by the "ci" tab when a tag is being viewed. If
+	unspecified, `ci-url' is used instead. Default value: none. See also:
+	"CI URL EXPANSION".
+
+ci-url::
+	Url template used by the "ci" tab for refs which are not covered by
+	`ci-branch-url` or `ci-tag-url`. When at least one of the three ci url
+	settings is specified, cgit adds a "ci" tab which redirects to the
+	expanded url for the ref currently being viewed. Default value: none.
+	See also: "CI URL EXPANSION".
+
 clone-prefix::
 	Space-separated list of common prefixes which, when combined with a
 	repository url, generates valid clone urls for the repository. This
@@ -468,6 +485,18 @@ repo.branch-sort::
 	list, and when set to "name" enables ordering by branch name. Default
 	value: "name".
 
+repo.ci-branch-url::
+	Override the global setting `ci-branch-url' for this repository.
+	Default value: <ci-branch-url>. See also: "CI URL EXPANSION".
+
+repo.ci-tag-url::
+	Override the global setting `ci-tag-url' for this repository. Default
+	value: <ci-tag-url>. See also: "CI URL EXPANSION".
+
+repo.ci-url::
+	Override the global setting `ci-url' for this repository. Default
+	value: <ci-url>. See also: "CI URL EXPANSION".
+
 repo.clone-url::
 	A list of space-separated urls which can be used to clone this repo.
 	Default value: none. See also: "MACRO EXPANSION".
@@ -776,6 +805,42 @@ the environment variables defined in "FILTER API":
 - repo.clone-url
 
 
+CI URL EXPANSION
+----------------
+The options `ci-url', `ci-branch-url' and `ci-tag-url' (and their
+`repo.'-prefixed counterparts) are url templates in which the following
+tokens are substituted when the "ci" tab is followed:
+
+$ref::
+	The name of the branch or tag currently being viewed.
+
+$repo::
+	The url of the repository, i.e. the value of `repo.url'.
+
+$slug::
+	$repo with any ".git" suffix removed and all slashes replaced by
+	dashes, e.g. "sayauz/web.git" becomes "sayauz-web".
+
+Two consecutive dollar signs produce a single literal one, and any other
+"$" is left untouched. Tokens are substituted verbatim, so the resulting
+url must already be properly encoded.
+
+When a tag is being viewed, `ci-tag-url' is used; for anything else
+`ci-branch-url' is used. Whichever of the two applies falls back to
+`ci-url' when it is unset, and the "ci" tab yields "404 Not found" when
+neither is set for the current ref. This makes it possible to point at a
+Jenkins multibranch pipeline, where branches and tags live at different
+locations:
+
+	ci-branch-url=https://ci.example.org/job/$slug/job/$ref
+	ci-tag-url=https://ci.example.org/job/$slug/view/tags/job/$ref
+
+Setting `repo.ci-url' discards the values which the repository would
+otherwise inherit from the global `ci-branch-url' and `ci-tag-url', so
+that a single repository can be pointed at a different ci system without
+having to override both of them.
+
+
 CACHE
 -----
 
@@ -828,6 +893,11 @@ clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
 css=/css/cgit.css
 
 
+# Add a "ci" tab pointing at a Jenkins multibranch pipeline
+ci-branch-url=https://ci.foo.org/job/$slug/job/$ref
+ci-tag-url=https://ci.foo.org/job/$slug/view/tags/job/$ref
+
+
 # Show owner on index page
 enable-index-owner=1