refactor(docs): api: systems: gitlab: write 'TicketSystem'

docs/api/systems/gitlab/ticket-system.md

-# Gitlab-Ticketsystem
+# GitLab-Ticketsystem
 
-!!! todo
-    write usage api docs
+This documents GitLab specific things for the integration to this library.
+For the global parts, see in the [core sections Ticketsystem site][core-ts].
+
+## create new instance
+
+A `GitlabTicketSystem` object is always referencing a specific GitLab project.
+Mandatory information to instantiate it, are the GitLab instances base url and the projects id.
+
+For public accessible actions, it can be used anonymously.
+Other operations have to be authenticated using an api-key.
+
+For all calls the GitLab api V4 is used (at the time of writing this, the only available one).
+If not configured otherwise, connections will use https.
+
+### by URI
+
+```java
+// recommended option
+GitlabTicketSystem ts = (GitlabTicketSystem) TicketSystem.fromUri("<uri>");
+
+// second possible declaration
+TicketSystem<
+    GitlabTicket,
+    GitlabTicketSystem,
+    GitlabTicketBuilder,
+    GitlabFilter
+    > gl = TicketSystem.fromUri("<uri>");
+```
+
+The first declaration option uses the child-class from the GitLab implementation directly.
+The second option uses the parent-class instead,
+defining the different implementations with Generics.
+
+Use the first option, if you're sure you want to use GitLab no matter what.
+This way you can see GitLab specific methods,
+whereas the second option keeps you limited on the global defined ones.
+If you may switch ticket systems in the future,
+the second option forces you to not use system specific stuff, making a transition easier.
+
+The URI to pass has to match this format:
+```
+unifiedticketing:gitlab:[http://|https://]<base url>:<project id>[:api key]
+```
+
+- protocol for http/https is optional. If not given, https is used
+- base url can contain also non-standard port hosted gitlab instances
+- api key if authentication needed, otherwise anonymous access is used
+
+??? example "URI examples"
+    - non-https anonymous, project 234, public gitlab  
+        `unifiedticketing:gitlab:http://wwww.gitlab.com:234`
+    - implicit https authenticated, project 234, public gitlab  
+        `unifiedticketing:gitlab:gitlab.com:234:1234896102765abcddbda324bb3a3`
+    - explicit https authenticated, project 42, fictional gitlab, non-standard port  
+        `unifiedticketing:gitlab:https://gitlab.example.org:8080:42:1234896102765abcddbda324bb3a3`
+
+### by builder
+
+For instantiation from the builder,
+mostly the same like building by URI applies.
+
+!!! warning
+    Passing the base url ensure the protocol (http or https) is removed
+
+??? example "builder examples"
+    - non-https anonymous, project 234, public gitlab  
+        ```java
+        GitlabTicketSystem ts = TicketSystem.fromBuilder()
+            .gitlab()
+            .withBaseUrl("www.gitlab.com")
+            .withHttp()
+            .withProjectId(234) // String and int variant available
+            .build();
+        ```
+    - implicit https authenticated, project 234, public gitlab  
+        ```java
+        GitlabTicketSystem ts = TicketSystem.fromBuilder()
+            .gitlab()
+            .withBaseUrl("gitlab.com")
+            .withProjectId("234")
+            .withApiKey("1234896102765abcddbda324bb3a3")
+            .build();
+        ```
+    - explicit https authenticated, project 42, fictional gitlab, non-standard port  
+        ```java
+        GitlabTicketSystem ts = TicketSystem.fromBuilder()
+            .gitlab()
+            .withBaseUrl("gitlab.example.org:8080")
+            .withHttps()
+            .withProjectId(42)
+            .withApiKey("1234896102765abcddbda324bb3a3")
+            .build();
+        ```
+
+## list tickets
+
+!!! warning "default pagination"
+    GitLab has a default pagination on _20_ elements per page.
+    Highest possible value is _100_ elements. [[Link]][gl-api-docs-pagination]
+
+!!! warning "mutual exclusive filters"
+    if you filter for assignees, you can only use either assignee-ids or their usernames. [[Link]][gl-api-docs-issues-list]
+
+## get single ticket
+
+!!! info
+    This uses the list mechanism internally,
+    with the given issue-id as filter and just unwraps it from the received list.
+
+## create new ticket
+
+For a new GitLab ticket a title is mandatory.
+Everything else is optional.
+
+!!! example "minimal example"
+    ```java
+    GitlabTicket = ts.createTicket()
+        .title("my new ticket")
+        .create();
+    ```
+
+Setting an assignee, has to be by user-id. Setting by user name is not supported.
+
+[core-ts]: ../../core/ticket-system.md
+[gl-api-docs-issues-list]: https://docs.gitlab.com/ee/api/issues.html#list-issues
+[gl-api-docs-pagination]: https://docs.gitlab.com/ee/api/#pagination