mirror of
https://github.com/jdalrymple/gitbeaker.git
synced 2026-01-25 16:04:01 +00:00
docs: Updating README and performing some basic linting
This commit is contained in:
Justin
parent
4f3066f167
commit
ce408be0df
218
README.md
218
README.md
@ -8,23 +8,26 @@
|
||||
[](https://codecov.io/gh/jdalrymple/node-gitlab)
|
||||
[](https://github.com/semantic-release/semantic-release)
|
||||
[](http://commitizen.github.io/cz-cli/)
|
||||
[](https://img.shields.io/badge/code%20style-prettier-ff69b4.svg)
|
||||
[](https://packagephobia.now.sh/result?p=gitlab)
|
||||
[](https://github.com/jdalrymple/node-gitlab/blob/master/LICENSE.md)
|
||||
|
||||
# node-gitlab
|
||||
|
||||
🤖 [GitLab](https://github.com/gitlabhq/gitlabhq) API NodeJS library with full support of all the [Gitlab API](https://github.com/gitlabhq/gitlabhq/tree/master/doc/api) services.
|
||||
🤖 [GitLab](https://github.com/gitlabhq/gitlabhq) API NodeJS library with full support of all the [Gitlab API](https://github.com/gitlabhq/gitlabhq/tree/master/doc/api) services.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Install](#install)
|
||||
- [Usage](#usage)
|
||||
- [Supported APIs](#supported-apis)
|
||||
- [Import](#import)
|
||||
- [Specific Imports](#specific-imports)
|
||||
- [Bundle Imports](#bundle-imports)
|
||||
- [Examples](#examples)
|
||||
- [Pagination](#pagination)
|
||||
- [Sudo](#sudo)
|
||||
- [Supported APIs](#supported-apis)
|
||||
- [Import](#import)
|
||||
- [Specific Imports](#specific-imports)
|
||||
- [Bundle Imports](#bundle-imports)
|
||||
- [Examples](#examples)
|
||||
- [Pagination](#pagination)
|
||||
- [Sudo](#sudo)
|
||||
- [Custom Request Libraries](#custom-request-libraries)
|
||||
- [Migrating from node-gitlab](#migrating-from-node-gitlabnode-gitlab)
|
||||
- [Docs](#docs)
|
||||
- [Development](#development)
|
||||
@ -33,7 +36,6 @@
|
||||
- [License](#licence)
|
||||
- [Changelog](#changelog)
|
||||
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
@ -42,8 +44,11 @@ npm install gitlab
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Supported APIs
|
||||
|
||||
The API's that are currently supported are:
|
||||
|
||||
```
|
||||
// General
|
||||
ApplicationSettings
|
||||
@ -57,6 +62,7 @@ Keys
|
||||
Licence
|
||||
LicenceTemplates
|
||||
Lint
|
||||
Markdown
|
||||
Namespaces
|
||||
NotificationSettings
|
||||
PagesDomains
|
||||
@ -132,6 +138,7 @@ UserKeys
|
||||
UserGPGKeys
|
||||
|
||||
```
|
||||
|
||||
### Import
|
||||
|
||||
URL to your GitLab instance should not include `/api/v4` path.
|
||||
@ -139,26 +146,31 @@ URL to your GitLab instance should not include `/api/v4` path.
|
||||
Instantiate the library using a basic token created in your [Gitlab Profile](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html)
|
||||
|
||||
```javascript
|
||||
// ES6 (>=node 8.0.0)
|
||||
import Gitlab from 'gitlab';
|
||||
|
||||
// ES5, assuming Promise and Object.assign are available
|
||||
const Gitlab = require('gitlab/dist/es5').default
|
||||
// ES6 (>=node 8.9.0)
|
||||
import { Gitlab } from 'gitlab';
|
||||
|
||||
// ES5, assuming native or polyfilled Promise is available
|
||||
const { Gitlab } = require('gitlab');
|
||||
|
||||
// Instantiating
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
})
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456', // Can be created in your profile.
|
||||
});
|
||||
|
||||
// Or, use a OAuth token instead!
|
||||
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
oauthToken: 'abcdefghij123456'
|
||||
})
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
oauthToken: 'abcdefghij123456',
|
||||
});
|
||||
|
||||
// You can also use a CI job token:
|
||||
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to https://gitlab.com
|
||||
jobToken: process.env.CI_JOB_TOKEN,
|
||||
});
|
||||
```
|
||||
|
||||
#### Specific Imports
|
||||
@ -169,22 +181,20 @@ Sometimes you don't want to import and instantiate the whole Gitlab API, perhaps
|
||||
import { Projects } from 'gitlab';
|
||||
|
||||
const service = new Projects({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
})
|
||||
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456', // Can be created in your profile.
|
||||
});
|
||||
```
|
||||
|
||||
#### Bundle Imports
|
||||
|
||||
It can be annoying to have to import all the API's pertaining to a specific resource. For example, the Projects resource is composed of many API's, Projects, Issues, Labels, MergeRequests, etc. For convenience, there is a Bundle export for importing and instantiating all these related API's at once.
|
||||
|
||||
|
||||
```javascript
|
||||
import { ProjectsBundle } from 'gitlab';
|
||||
|
||||
const services = new ProjectsBundle({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
})
|
||||
|
||||
@ -195,7 +205,9 @@ etc..
|
||||
```
|
||||
|
||||
Currently there are three Bundles:
|
||||
|
||||
1. ProjectsBundle which includes:
|
||||
|
||||
```
|
||||
Branches
|
||||
Commits
|
||||
@ -242,6 +254,7 @@ Triggers
|
||||
```
|
||||
|
||||
2. UsersBundle which includes:
|
||||
|
||||
```
|
||||
Users,
|
||||
UserCustomAttributes,
|
||||
@ -252,6 +265,7 @@ UserGPGKeys
|
||||
```
|
||||
|
||||
3. GroupsBundle which includes:
|
||||
|
||||
```
|
||||
Groups
|
||||
GroupAccessRequests
|
||||
@ -268,62 +282,69 @@ EpicNotes
|
||||
EpicDiscussions
|
||||
```
|
||||
|
||||
### Using XMLHttpRequest
|
||||
This package uses the [Request](https://github.com/request/request) library by default, which is built into Node. However, if your code is running in a browser, you can get better built-in resolution of proxies and self-signed certificates by using the browser's XMLHttpRequest implementation instead:
|
||||
#### Handling HTTPS certificates
|
||||
|
||||
```javascript
|
||||
import Gitlab from 'gitlab';
|
||||
If your Gitlab server is running via HTTPS, the proper way to pass in your certificates is via a `NODE_EXTRA_CA_CERTS` environment key, like this:
|
||||
|
||||
```js
|
||||
"scripts": {
|
||||
"start": "NODE_EXTRA_CA_CERTS=./secrets/3ShapeCA.pem node bot.js"
|
||||
},
|
||||
```
|
||||
|
||||
Although we don't encourage it, if you absolutely must allow insecure certificates, you can instantiate the API with `rejectAuthorized` set to `false` like this:
|
||||
|
||||
```
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
token: 'abcdefghij123456', // Can be created in your profile.
|
||||
|
||||
useXMLHttpRequest: true // Use the browser's XMLHttpRequest instead of Node's Request library
|
||||
url: '...',
|
||||
token: '...',
|
||||
rejectUnauthorized: false
|
||||
})
|
||||
```
|
||||
|
||||
**WARNING:** Currently this option does not support the `multipart/form-data` content type, and therefore the endpoint for [uploading a file to a project](https://docs.gitlab.com/ee/api/projects.html#upload-a-file) will not work correctly. All other endpoints should work exactly as expected.
|
||||
> **NOTE**: _Using `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'` will not work with the `gitlab` library. The `rejectUnauthorized` key is the only way to allow insecure certificates to be bypassed._
|
||||
|
||||
### Examples
|
||||
|
||||
Once you have your library instantiated, you can utilize many of the API's functionality:
|
||||
|
||||
Using the await/async method
|
||||
|
||||
```javascript
|
||||
import Gitlab from 'gitlab';
|
||||
import { Gitlab } from 'gitlab';
|
||||
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456', // Can be created in your profile.
|
||||
});
|
||||
|
||||
// Listing users
|
||||
let users = await api.Users.all();
|
||||
|
||||
// Or using Promise-Then notation
|
||||
api.Projects.all()
|
||||
.then((projects) => {
|
||||
console.log(projects)
|
||||
})
|
||||
api.Projects.all().then(projects => {
|
||||
console.log(projects);
|
||||
});
|
||||
```
|
||||
|
||||
General rule about all the function parameters:
|
||||
|
||||
- If its a required parameter, it is a named argument in the functions
|
||||
- If its an optional parameter, it is defined in a options object following the named arguments
|
||||
|
||||
ie.
|
||||
|
||||
```javascript
|
||||
import Gitlab from 'gitlab';
|
||||
import { Gitlab } from 'gitlab';
|
||||
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456', // Can be created in your profile.
|
||||
});
|
||||
|
||||
api.Projects.create(projectId, {
|
||||
//options defined in the Gitlab API documentation
|
||||
})
|
||||
//options defined in the Gitlab API documentation
|
||||
});
|
||||
```
|
||||
|
||||
### Pagination
|
||||
@ -331,29 +352,27 @@ api.Projects.create(projectId, {
|
||||
For any .all() function on a resource, it will return all the items from Gitlab. This can be troublesome if there are many items, as the request it self can take a while to be fulfilled. As such, a maxPages option can be passed to limit the scope of the all function.
|
||||
|
||||
```javascript
|
||||
import Gitlab from 'gitlab';
|
||||
import { Gitlab } from 'gitlab';
|
||||
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456', // Can be created in your profile.
|
||||
});
|
||||
|
||||
let projects = await api.Projects.all({ maxPages:2 });
|
||||
|
||||
let projects = await api.Projects.all({ maxPages: 2 });
|
||||
```
|
||||
|
||||
You can also use this in conjunction to the perPage argument which would override the default of 30 per page set by Gitlab:
|
||||
|
||||
```javascript
|
||||
import Gitlab from 'gitlab';
|
||||
import { Gitlab } from 'gitlab';
|
||||
|
||||
const api = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456', // Can be created in your profile.
|
||||
});
|
||||
|
||||
let projects = await api.Projects.all({ maxPages:2, perPage:40 });
|
||||
|
||||
let projects = await api.Projects.all({ maxPages: 2, perPage: 40 });
|
||||
```
|
||||
|
||||
Additionally, if you would like to get back the pagination information, to know how many total pages there are for example, pass the pagination option `showPagination` in addition to either the
|
||||
@ -361,7 +380,11 @@ Additionally, if you would like to get back the pagination information, to know
|
||||
|
||||
```javascript
|
||||
...
|
||||
let { data, pagination } = await api.Projects.all({ perPage:40, maxPages:2, showPagination: true });
|
||||
const { data, pagination } = await api.Projects.all({
|
||||
perPage:40,
|
||||
maxPages:2,
|
||||
showPagination: true
|
||||
});
|
||||
...
|
||||
```
|
||||
|
||||
@ -381,31 +404,51 @@ pagination: {
|
||||
}
|
||||
```
|
||||
|
||||
> Note: supplying any pagination restrictions is call intensive. Some resources will require many requests which can put a significant load on the Gitlab Server. The general best practice would be setting the page request option to only return the first page if all results are not required.
|
||||
|
||||
### Sudo
|
||||
|
||||
For private gitlab instances, administrators are able to impersonate users through the API. To do so, you have to set the 'Sudo' header on the services you want to impersonate the user for.
|
||||
|
||||
For example, if you want to disable notifications for a specific user:
|
||||
```javascript
|
||||
import Gitlab from 'gitlab';
|
||||
|
||||
const { NotificationSettings } = new Gitlab({
|
||||
url: 'http://example.com', // Defaults to http://gitlab.com
|
||||
```javascript
|
||||
import { NotificationSettings } from 'gitlab';
|
||||
|
||||
const service = new NotificationSettings({
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
sudo: 8 // Can be the user ID or a username
|
||||
});
|
||||
|
||||
await NotificationSettings.edit({
|
||||
await service.edit({
|
||||
level: NotificationSettings.LEVELS.DISABLED
|
||||
})
|
||||
```
|
||||
|
||||
## Migrating from node-gitlab/node-gitlab
|
||||
### Custom Request Libraries
|
||||
|
||||
With the success of this library thanks to the community, this has become the main npm package to interact with the Gitlab API. As such, there will be a little bit of growing pains for those upgrading from the original node-gitlab v1.8 to our newest 3.0.0 release, far too many to list here. I hope the library is written clearly enough to ease this transition, but if there is anything that you're having trouble with please feel free to create an issue! If not myself, someone will definitely have the answer to help get you all setup up as quickly as possible.
|
||||
There is another constructor parameter that allows the user to specify their own custom request library
|
||||
as long as it has a similar API to ky. To specify the library, simply set the `requester` property when
|
||||
instatiating a service:
|
||||
|
||||
An example can be seen in the [KyRequester.ts](./src/infrastructure/KyRequester.ts) file
|
||||
|
||||
```javascript
|
||||
import { Gitlab } from 'gitlab';
|
||||
import YourCustomRequester from 'custom-requester';
|
||||
|
||||
const api = new Gitlab({
|
||||
host: 'http://example.com', // Defaults to https://gitlab.com
|
||||
token: 'abcdefghij123456' // Can be created in your profile.
|
||||
requester: YourCustomRequester
|
||||
});
|
||||
|
||||
```
|
||||
|
||||
## Docs
|
||||
|
||||
Although there are the [official docs](https://github.com/gitlabhq/gitlabhq/tree/master/doc/api) for the API, there are some extra goodies offered by this package! After the 3.0.0 release, the next large project will be putting together proper documentation for these goodies [#39]! Stay tuned!!
|
||||
Although there are the [official docs](https://github.com/gitlabhq/gitlabhq/tree/master/doc/api) for the API, there are some extra goodies offered by this package! After the 3.0.0 release, the next large project will be putting together proper documentation for these goodies [#39]! Stay tuned!!
|
||||
|
||||
## Development
|
||||
|
||||
@ -418,13 +461,11 @@ $ npm install
|
||||
$ npm build
|
||||
```
|
||||
|
||||
And then inside whatever project you are using `node-gitlab` in you change your references to use that repo. In your package.json of that upstream project change:
|
||||
And then inside whatever project you are using `node-gitlab` in you change your references to use that repo. In your package.json of that upstream project change:
|
||||
|
||||
```json
|
||||
"dependencies": {
|
||||
...
|
||||
"node-gitlab": "2.1.0"
|
||||
...
|
||||
"gitlab": "5.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
@ -432,15 +473,13 @@ to this
|
||||
|
||||
```json
|
||||
"dependencies": {
|
||||
...
|
||||
"node-gitlab": "<path-to-your-clone>"
|
||||
...
|
||||
"gitlab": "<path-to-your-clone>"
|
||||
}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Testing is a work-in-progress right now but here is the start.
|
||||
Testing is a work-in-progress right now but here is the start.
|
||||
|
||||
1. First run Gitlab in a docker container:
|
||||
|
||||
@ -449,11 +488,11 @@ docker-compose -f docker-compose.test.yml up
|
||||
```
|
||||
|
||||
1. Once GitLab is up on localhost:8080, get the two environment variables from the docker image could
|
||||
either export them into environment variables locally:
|
||||
either export them into environment variables locally:
|
||||
|
||||
```bash
|
||||
export PERSONAL_ACCESS_TOKEN=$(docker exec -it gitlab bash -lc 'printf "%q" "${PERSONAL_ACCESS_TOKEN}"')
|
||||
export GITLAB_URL=$(docker exec -it gitlab bash -lc 'printf "%q" "${GITLAB_URL}"')
|
||||
export GITLAB_URL=$(docker exec -it gitlab bash -lc 'printf "%q" "${GITLAB_URL}"')
|
||||
```
|
||||
|
||||
1. Now run the tests
|
||||
@ -473,7 +512,6 @@ PERSONAL_ACCESS_TOKEN='abcdefg' GITLAB_URL='http://localhost:8080' npm run test
|
||||
|
||||
> Note it may take about 3 minutes to get the variables while Gitlab is starting up in the container
|
||||
|
||||
|
||||
## Contributors
|
||||
|
||||
This started off as a fork from [node-gitlab](https://github.com/node-gitlab/node-gitlab) but I ended up rewriting much of the code. Here are the original work's [contributors](https://github.com/node-gitlab/node-gitlab#contributors).
|
||||
@ -493,15 +531,16 @@ This started off as a fork from [node-gitlab](https://github.com/node-gitlab/nod
|
||||
- [Claude Abounegm](https://github.com/claude-abounegm)
|
||||
- [Stefan Hall](https://github.com/Marethyu1)
|
||||
- [Jordan Wallet](https://github.com/Mr-Wallet)
|
||||
- [Ev Haus](https://github.com/EvHaus)
|
||||
- [Ev Haus](https://github.com/EvHaus)
|
||||
- [zhao0](https://github.com/zhao0)
|
||||
- [Joshua Grosso](https://github.com/jgrosso)
|
||||
- [Frédéric Boutin](https://github.com/fboutin-pmc)
|
||||
- [Isaac Ouellet Therrien](https://github.com/yonguelink)
|
||||
- [Pavel Birukov](https://github.com/r00ger)
|
||||
- [Pavel Birukov](https://github.com/pablobirukov)
|
||||
- [Sharma-Rajat](https://github.com/Sharma-Rajat)
|
||||
- [Joseph Petersen](https://github.com/casz)
|
||||
- [Igor Katsuba](https://github.com/Defenderbass)
|
||||
- [Igor Katsuba](https://github.com/IKatsuba)
|
||||
- [Giuseppe Angri](https://github.com/giuseppeangri)
|
||||
- [Michael Townsend](https://github.com/Continuities)
|
||||
- [bodtx](https://github.com/bodtx)
|
||||
- [Artem](https://github.com/arthot)
|
||||
@ -511,6 +550,23 @@ This started off as a fork from [node-gitlab](https://github.com/node-gitlab/nod
|
||||
- [Norm MacLennan](https://github.com/maclennann)
|
||||
- [jnovick](https://github.com/jnovick)
|
||||
- [Fabian Aussems](https://github.com/mozinator)
|
||||
- [jennparise](https://github.com/jennparise)
|
||||
- [Michael Matzka](https://github.com/mimaidms)
|
||||
- [CraigAllardyce](https://github.com/CraigAllardyce)
|
||||
- [Bruno Guimarães](https://github.com/brunobastosg)
|
||||
- [Louis Cherel](https://github.com/Musinux)
|
||||
- [Lukas Eipert](https://github.com/leipert)
|
||||
- [Maximilian Krauß](https://github.com/maximilian-krauss)
|
||||
- [Evolution Gaming](https://github.com/evolution-gaming)
|
||||
- [WEBER Logan](https://github.com/Neonox31)
|
||||
- [Anton Zhukov](https://github.com/MrCheater)
|
||||
- [Nic Loomans](https://github.com/beaverusiv)
|
||||
- [Jennifer Everhart]()
|
||||
- [Carl Kittelberger](https://github.com/icedream)
|
||||
- [Patrik Votoček](https://github.com/Vrtak-CZ)
|
||||
- [Kyrylo Fedorov](https://github.com/Kyr)
|
||||
- [Claudio Vellage](https://github.com/jdalrymple/LRH539)
|
||||
- [Seb0uil](https://github.com/seb0uil)
|
||||
|
||||
## License
|
||||
|
||||
@ -519,5 +575,3 @@ This started off as a fork from [node-gitlab](https://github.com/node-gitlab/nod
|
||||
## Changelog
|
||||
|
||||
[Here](https://github.com/jdalrymple/node-gitlab/blob/master/CHANGELOG.md)
|
||||
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user