= GitLab raw content include processor
:toc:


It's a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including raw content from GitLab repositories.


== Synopsis

[source, asciidoc]
----
include::gitlab/$OWNER/$REPO[rev=$COMMIT, path=$FILEPATH]
----


== Extra notes

A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[personal access token] is most likely required.
Get one and place the value in an environment variable `GITLAB_API_PERSONAL_ACCESS_TOKEN`.


== Attributes

There are some attributes required to be passed.

- `rev` is the commit to be checked out.
- `path` is the file path to be included.

Aside from the required attributes, there are optional attributes to configured further.

- `domain` is the domain of the GitLab instance.
By default, it points to the `gitlab.com` official instance.

- `version` is the version string of the API to be used.
By default, it uses version `v4`.


== Example usage

- `include::gitlab:gitlab-org/gitlab[rev=master, path=README.md]` should include the README content from the master branch of link:https://gitlab.com/gitlab-org/gitlab/[GitLab source code].

- `include::freedesktop-sdk/freedesktop-sdk[rev=bcb3e0de957519e87a4c7b8c0e40af9876e531e7, path=.gitlab-ci.yml]` should transclude the GitLab CI configuration from link:https://gitlab.com/freedesktop-sdk/freedesktop-sdk[Freedesktop SDK].

- `include::World/warp[domain=gitlab.gnome.org, rev=v0.5.2, path=meson_options.txt]` includes `meson_options.txt` from link:https://gitlab.gnome.org/World/warp/[Warp source code] at v0.5.2.