ticket-system.md

# GitHub-Ticketsystem

This documents GitHub 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 `GithubTicketSystem` object is always referencing a specific GitHub project.
Mandatory information to instantiate it, are the GitHub instances base url, the project owner and project.

For public accessible actions, it can be used anonymously.
Other operations have to be authenticated using an username and a personal access token.

For all calls the `accept` header will be set to `application/vnd.github.v3+json`.
If not configured otherwise, connections will use `https`.

### by URI

```java
// recommended option
GithubTicketSystem ts = (GithubTicketSystem) TicketSystem.fromUri("<uri>");

// second possible declaration
TicketSystem<
    GithubTicket,
    GithubTicketSystem,
    GithubTicketBuilder,
    GithubFilter
    > gl = TicketSystem.fromUri("<uri>");
```

The first declaration option uses the child-class from the GitHub 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 GitHub no matter what.
This way you can see GitHub 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:github:[http://|https://]<base url>::<owner>:<repo>[:<username>:<apikey>]
```

- protocol for http/https is optional. If not given, https is used
- base url can contain also non-standard port hosted github instances
- username and api key if authentication needed, otherwise anonymous access is used

??? example "URI examples"
    - non-https anonymous, owner me, project hello-world, public gitlab  
        `unifiedticketing:github:http://api.github.com::me:hello-world`
    - implicit https authenticated, owner me, project hello-world, public gitlab  
        `unifiedticketing:github:api.github.com::me:hello-world:me:1234896102765abcddbda324bb3a3`
    - explicit https authenticated, owner me, project hello-world, fictional github, non-standard port  
        `unifiedticketing:github:https://api.github.example.org:8080::me:hello-world:me: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, owner me, repo hello-world, public github  
        ```java
        GithubTicketSystem ts = TicketSystem.fromBuilder()
            .github()
            .withBaseUrl("api.github.com")
            .withHttp()
            .withOwner("me")
            .withRepo("hello-world")
            .build();
        ```
    - implicit https authenticated, owner me, repo hello-world, public github  
        ```java
        GithubTicketSystem ts = TicketSystem.fromBuilder()
            .github()
            .withBaseUrl("api.github.com")
            .withOwner("me")
            .withRepo("hello-world")
            .withAuthentication("me", "1234896102765abcddbda324bb3a3")
            .build();
        ```
    - explicit https authenticated, owner me, repo hello-world, fictional github, non-standard port  
        ```java
        GithubTicketSystem ts = TicketSystem.fromBuilder()
            .github()
            .withBaseUrl("api.github.example.org:8080")
            .withHttps()
            .withOwner("me")
            .withRepo("hello-world")
            .withAuthentication("me", "1234896102765abcddbda324bb3a3")
            .build();
        ```

## list tickets

!!! warning "default pagination"
    GitHub has a default pagination on _30_ elements per page.
    Highest possible value is _100_ elements. [[Link]][api-docs-pagination]

!!! info "assignees"
    GitHub implementation supports the fields `id` and `username`.
    If ticket has no assignees, assignee field stays `null`.

From the filters shown on the global `TicketSystem` docs,
the ones for title, description filter and ticket id's are not natively supported by the GitHub API.
If such a filter is used,
this get's done locally after receiving the response from GitHub,
before handing it to the user.

## get single ticket

As the GitHub API doesn't support a ticket-id filter on the list endpoint,
the method for getting a single ticket by it's id uses the single ticket endpoint.

If you use the Filter class with a single ticket id as only filter,
you end up fetching all tickets of that repo, filtering out all non matching ones locally.

## create new ticket

For a new GitHub ticket a title is mandatory.
Everything else is optional.

!!! example "minimal example"
    ```java
    GithubTicket = ts.createTicket()
        .title("my new ticket")
        .create();
    ```

Setting an assignee, has to be by user login name.

[core-ts]: ../../core/ticket-system.md
[api-docs-issues-list]: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues#list-repository-issues
[api-docs-pagination]: https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api#pagination