GitLab-Ticketsystem

This documents GitLab specific things for the integration to this library. For the global parts, see in the core sections Ticketsystem site.

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

// 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

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

builder examples

• non-https anonymous, project 234, public gitlab
  

  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
  

  GitlabTicketSystem ts = TicketSystem.fromBuilder()
      .gitlab()
      .withBaseUrl("gitlab.com")
      .withProjectId("234")
      .withApiKey("1234896102765abcddbda324bb3a3")
      .build();
  

• explicit https authenticated, project 42, fictional gitlab, non-standard port
  

  GitlabTicketSystem ts = TicketSystem.fromBuilder()
      .gitlab()
      .withBaseUrl("gitlab.example.org:8080")
      .withHttps()
      .withProjectId(42)
      .withApiKey("1234896102765abcddbda324bb3a3")
      .build();
  

list tickets

default pagination

GitLab has a default pagination on 20 elements per page. Highest possible value is 100 elements. [Link]

mutual exclusive filters

if you filter for assignees, you can only use either assignee-ids or their usernames. [Link]

assignees

GitLab implementation supports the fields id, username and full name. If ticket has no assignee, assignee field stays null.

From the filters shown on the global TicketSystem docs, the ones for regex-matching are not natively supported by the GitLab API. If such a filter is used, this get's done locally after receiving the response from GitLab, before handing it to the user.

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.

minimal example

GitlabTicket = ts.createTicket()
    .title("my new ticket")
    .create();

Setting an assignee, has to be by user-id. Setting by user name is not supported.