ui-ci: let a ci-filter decide whether the tab is shown

cgit cannot know whether the ref being viewed actually has a pipeline, so
the "ci" tab is offered for every ref and only reveals a missing one once
followed. Probing the ci system from cgit is not an option: the tab is
part of the page header, so it would mean a blocking request for every
page of every repository, cgit links no http client, and job pages are
usually not readable anonymously.

Add a ci filter instead, which receives the ref, whether it is a branch or
a tag, and the expanded url, and answers with its exit status. This keeps
credentials, timeouts and caching in a script, where they belong;
filters/ci-jenkins.sh demonstrates all three against Jenkins' REST API.

The verdict is memoized, so the filter runs once per request rather than
once for the tab and again for the redirect, and it governs the page as
well as the tab, so a hidden tab cannot be reached by typing the url.

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

1 files changed, 27 insertions, 0 deletions

diff --git a/cgitrc.5.txt b/cgitrc.5.txt
index 145a17e..c03579f 100644
--- a/cgitrc.5.txt
+++ b/cgitrc.5.txt
@@ -105,6 +105,11 @@ ci-branch-url::
 	unspecified, `ci-url` is used instead. Default value: none. See also:
 	"CI URL EXPANSION".
 
+ci-filter::
+	Specifies a command which decides whether the "ci" tab is shown for
+	the ref currently being viewed, which is useful when only some refs
+	have a pipeline. Default value: none. See also: "FILTER API".
+
 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:
@@ -489,6 +494,10 @@ 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-filter::
+	Override the default ci-filter. Default value: none. See also:
+	"enable-filter-overrides". See also: "FILTER API".
+
 repo.ci-tag-url::
 	Override the global setting `ci-tag-url' for this repository. Default
 	value: <ci-tag-url>. See also: "CI URL EXPANSION".
@@ -739,6 +748,20 @@ auth filter::
 	Please see `filters/simple-authentication.lua` for a clear example
 	script that may be modified.
 
+ci filter::
+	This filter is given three parameters: the name of the branch or tag
+	being viewed, the string "branch" or "tag" to say which of the two it
+	is, and the ci url that the "ci" tab would redirect to. It decides
+	whether that tab is shown at all, by returning zero from the exit code
+	/ close function to show it and non-zero to hide it. Nothing is written
+	to its standard input, and it must not write to standard output, since
+	that would land in the middle of the page being rendered.
+
+	The filter is consulted while rendering every page of the repository,
+	not only ref pages, so a filter which contacts the ci system should
+	cache its verdict and use a short timeout. Please see
+	`filters/ci-jenkins.sh` for an example.
+
 commit filter::
 	This filter is given no arguments. The commit message text that is to
 	be filtered is available on standard input and the filtered text is
@@ -840,6 +863,10 @@ 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.
 
+Note that cgit itself never contacts the ci system, so a tab shown for a
+ref which has no pipeline only reveals that after being followed. Use
+`ci-filter' to suppress the tab in that case.
+
 
 CACHE
 -----