Skip to content

Allow activation of URI includes for AsciiDoc integration

Proposal

Allow (and document) how to allow URI includes for AsciiDoc integration.

The current GitLab documentation https://docs.gitlab.com/ee/user/asciidoc.html#includes states:

// define -a allow-uri-read to allow content to be read from URI
include::https://example.org/installation.adoc[]

But, there is no documentation how to actually activate it. Is it possible to activate?

  • If so, how?
  • If not, please note this in the documentation.

Background

We have a self-hosted GitLab that we would like to activate URI includes for. It is vital to us since we want to include AsciiDoc files from various repositories (projects) in the same GitLab instance. Otherwise, we won't be able to be DRY.

Implementation guide

We're using a custom include processor from https://github.com/jirutka/asciidoctor-include-ext, and are also extending it in lib/gitlab/asciidoc/include_processor.rb.

Unfortunately it looks like it doesn't support remote URLs:

# With the changes above:
pry> Gitlab::Asciidoc.render('include::https://example.com/index.html[]', {})
=> "<div>\n<p><a href=\"https://example.com/index.html\" rel=\"nofollow noreferrer noopener\" target=\"_blank\">https://example.com/index.html</a></p>\n</div>"

# This works though:
pry> Asciidoctor.convert('include::https://example.com/index.html[]', safe: :unsafe, attributes: { 'allow-uri-read' => true })
=> "<div class=\"paragraph\">\n<p>&lt;!doctype html&gt;\n&lt;html&gt;\n&lt;head&gt;\n    &lt;title&gt;Example Domain&lt;/title&gt;</p>\n</div>\n<div class=\"literalblock\">\n<div class=\"content\">\n<pre>    &lt;meta charset=\"utf-8\" /&gt;\n    &lt;meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" /&gt;\n    &lt;meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" /&gt;\n    &lt;style type=\"text/css\"&gt;\n    body {\n        background-color: #f0f0f2;\n        margin: 0;\n        padding: 0;\n        font-family: -apple-system, system-ui, BlinkMacSystemFont, \"Segoe UI\", \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n        \n    }\n    div {\n        width: 600px;\n        margin: 5em auto;\n        padding: 2em;\n        background-color: #fdfdff;\n        border-radius: 0.5em;\n        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);\n    }\n    a:link, a:visited {\n        color: #38488f;\n        text-decoration: none;\n    }\n    @media (max-width: 700px) {\n        div {\n            margin: 0 auto;\n            width: auto;\n        }\n    }\n    &lt;/style&gt;    \n&lt;/head&gt;</pre>\n</div>\n</div>\n<div class=\"paragraph\">\n<p>&lt;body&gt;\n&lt;div&gt;\n    &lt;h1&gt;Example Domain&lt;/h1&gt;\n    &lt;p&gt;This domain is for use in illustrative examples in documents. You may use this\n    domain in literature without prior coordination or asking for permission.&lt;/p&gt;\n    &lt;p&gt;&lt;a href=\"https://www.iana.org/domains/example\"&gt;More information&#8230;&#8203;&lt;/a&gt;&lt;/p&gt;\n&lt;/div&gt;\n&lt;/body&gt;\n&lt;/html&gt;</p>\n</div>"

The gem adds some other features, and our own extension adds protection against recursive includes, so we probably want to keep it and would have to implement support for allow-read-uri in lib/gitlab/asciidoc/include_processor.rb.

It looks like we only need to tweak the arguments and path validation, the actual reading via OpenURI is already handled by Asciidoc::Reader, which the gem reuses:

Add Wiki setting at Admin level

There was a comment in !82689 (merged) by @alexkalderimis regarding making this setting configurable so that it's not global for the entire GitLab instance. It then has to be configurable for both group (wiki) and project (wiki + repository) level.

  • Introduce a new setting at Admin level, wiki_asciidoc_allow_uri_includes
    • Type will be a boolean
    • Default value: false
    • This is similar to an existing wiki setting at the instance level for page content size.
    • Instance level would give us a quick way to enable this across projects and groups.

Documentation update

Files to modify: doc/user/asciidoc.md, administration/wikis

Out of scope

Do NOT implement any features. This is outside the scope of this issue: "If it is not possible to enable URI includes for AsciiDoc integration, add this feature as an option. Ideally under the Admin section in the GUI."

This issue related to: #348685

Edited by Michael Le