README.md
1# DokuWiki Plugin GitLab-Api
2Dokuwiki plugin to display some information from a GitLab project.
3
4## Requirements
5
6The curl library (``php-curl``) for PHP is required.
7
8## Install
9
10Download the plugin GitLab-Api into the `${dokuwiki_root}/lib/plugins` folder and restart DokuWiki or use the Extension Manager.
11
12## Configuration
13
14The following values must be configured in the Configuration Manager:
15
16- **server.default**: Set your default GitLab url without slash ending. You can override this setting in `server.json` file.
17- **token.default**: Fill your admin token. You can override this setting in `server.json` file.
18
19## Syntax
20
21### Default Syntax
22
23```php
24<gitlab-api project-path="<NAMESPACE>/<SUB_DIRS>/<PROJECT_NAME>" />
25```
26
27- **NAMESPACE** is the namespace of your project.
28- **SUB_DIRS** is the sub-directories of your project if exists.
29- **PROJECT_NAME** is the name of your project.
30
31For instance, if your project is available at `http://gitlab.domain.com/ns/dir1/dir2/project`, then the syntax should be:
32
33```php
34<gitlab-api project-path="ns/dir1/dir2/project" />
35```
36
37### Display Information
38
39The plugin displays following information if you add corresponded parameter:
40
41- **milestones="n"** lists the latest $n$ milestones.
42- **commits="n"** lists the latest $n$ commits.
43- **issues="n"** lists the latest $n$ issues.
44- **pipelines="n"** lists the latest $n$ pipelines.
45
46For instance, if you want to see the latest 3 milestones, 10 commits, 5 issues, and 10 pipelines, then the syntax will be:
47
48```php
49<gitlab-api project-path="ns/dir/project" commits="10" issues="5" milestones="3" pipelines="10" />
50```
51
52### Override Server and Token
53
54There a JSON file `server.json` inside the root of plugin. You can add or change the servers and their tokens.
55
56For instance; you have a GitLab server namely `gitlab.home` and following JSON file:
57
58```json
59{
60 "gitlab.home": {
61 "url": "http://192.168.0.10",
62 "token": "aabbccddeeffgghh"
63 }
64}
65```
66
67Then you can add `server` parameter as follows:
68
69```php
70<gitlab-api server="gitlab.home" project-path="ns/project" />
71```
72
73## Thanks
74
75This plugis is an extended version of [Gitlab-Project](https://github.com/algorys/gitlabproject/). Thanks to [@algorys](https://github.com/algorys).
76