Skip to content

🦊πŸ§ͺ A comprehensive and typed Gitlab SDK for Node.js, Browsers, Deno and CLI

License

Notifications You must be signed in to change notification settings

zg-tools/gitbeaker

Β 
Β 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation


gitbeaker

CircleCI Code Climate maintainability CodeCov test coverage Auto All Contributors Prettier Licence: MIT

GitLab API NodeJS library with full support of all the Gitlab API services.

Table of Contents

Install

# Install from npm
npm install @gitbeaker/node # NodeJS default, index.es.js for esm

npm install @gitbeaker/browser # UMD default

npm -g install @gitbeaker/cli  # CLI

Getting Started

NodeJS

// ES6
import { Gitlab } from '@gitbeaker/node'; // All Resources
import { Projects } from '@gitbeaker/node'; // Just the Project Resource
//...etc

// ES5
const { Gitlab } = require('@gitbeaker/node');

Browser

// ES6
import { Gitlab } from '@gitbeaker/browser'; // All Resources
import { Projects } from '@gitbeaker/browser'; // Just the Project Resource
//...etc

// ES5
const { Gitlab } = require('@gitbeaker/browser');

OR through the script tag:

<script src="https://unpkg.com/@gitbeaker/browser/dist/index.es.js" />
<script>
  const { Gitlab } = gitbeaker;
</script>

CLI

The CLI export functions in a similar manner, following the pattern:

gitbeaker [service name] [method name] --config_args pos_arg1 pos_arg2 --opts_arg1

Where:

  • service name is any of the supported API names
  • method name is any of the supported commands on that API service (See source for exceptions, but generally all, show, remove, update)
  • --config_args is any of general configuration arguments such as your personal token. These are outlined in the table above or by looking at the cli help menu pos_arg1 pos_arg2..etc is any of the arguments you would normally supply to the function. The names of the args should match the names in the method headers. These positional arguments can also be written as flag arguments, --pos_arg1 --pos_arg2..etc BUT must be written in the correct order.
  • --opts_arg1...etc is any of the optional arguments that you would normally supply to the function. Their names should match what the GitLab API docs request.

There is one small exception with the instantiating arguments, however, which must be supplied using a gb or gl prefix. ie.

# To get all the projects
gitbeaker projects all --gb-token="personaltoken"

# To get a project with id = 2
gitbeaker projects show --gl-token="personaltoken" 2

To reduce the annoyance of having to pass those configuration properties each time, it is also possible to pass the token and host information through environment variables in the form of GITLAB_[option name] or GITBEAKER_[option name] ie:

GITLAB_HOST=https://example.com
GITLAB_TOKEN=personaltoken
GITBEAKER_CAMELIZE=true

This could be set globally or using a .env file in the project folder.

Instantiation

Instantiate the library using a basic token created in your Gitlab Profile

const api = new Gitlab({
  token: 'personaltoken',
});

Available instantiating options:

Name Optional Default Description
host Yes https://gitlab.com Gitlab Instance Host URL
token No* N/A Personal Token. Required (one of the three tokens are required)
oauthToken No* N/A OAuth Token. Required (one of the three tokens are required)
jobToken No* N/A CI Job Token. Required (one of the three tokens are required)
rejectUnauthorized Yes true Http Certificate setting, Only applies to non-browser releases and HTTPS hosts urls
sudo Yes false Sudo query parameter
version Yes 4 API Version ID
camelize Yes false Camelizes all response body keys
requesterFn Yes @gitbeaker/node & @gitbeaker/cli : Got-based, @gitbeaker/browser: Ky-based. The @gitbeaker/core package does not have a default and thus must be set explicitly Request Library Wrapper
requestTimeout Yes 300000 Request Library Timeout in ms
profileToken Yes N/A Requests Profiles Token
profileMode Yes execution Requests Profiles Token

*One of these options must be supplied.

Typing Support

All the exposed types are exported though the Types export.

import { Types } from '@gitbeaker/node';

Docs

Although there are the official docs for the API, there are some extra goodies offered by this package! The next large project will be putting together proper documentation for these goodies [#39]! Stay tuned!!

Supported APIs

The API's that are currently supported are:

// General
ApplicationSettings
BroadcastMessages
Events
FeatureFlags
GeoNodes
GitignoreTemplates
GitLabCIYMLTemplates
Keys
License
LicenseTemplates
Lint
Namespaces
NotificationSettings
Markdown
PagesDomains
Search
SidekiqMetrics
Snippets
SystemHooks
Version
Wikis

// Groups
Groups
GroupAccessRequests
GroupBadges
GroupCustomAttributes
GroupIssueBoards
GroupMembers
GroupMilestones
GroupRunners
GroupVariables
GroupLabels
GroupDeployTokens
Epics
EpicIssues
EpicNotes
EpicDiscussions

// Users
Users
UserCustomAttributes
UserEmails
UserImpersonationTokens
UserSSHKeys
UserGPGKeys

// Projects
Branches
Commits
CommitDiscussions
ContainerRegistry
Deployments
DeployKeys
Environments
FreezePeriods
Issues
IssuesStatistics
IssueNotes
IssueNoteAwardEmojis
IssueDiscussions
IssueAwardEmojis
Jobs
Labels
MergeRequests
MergeRequestApprovals
MergeRequestAwardEmojis
MergeRequestDiscussions
MergeRequestNotes
Packages
PackageRegistry
Pipelines
PipelineSchedules
PipelineScheduleVariables
Projects
ProjectAccessRequests
ProjectBadges
ProjectCustomAttributes
ProjectImportExport
ProjectIssueBoards
ProjectHooks
ProjectMembers
ProjectMilestones
ProjectSnippets
ProjectSnippetNotes
ProjectSnippetDiscussions
ProjectSnippetAwardEmojis
ProtectedBranches
ProtectedTags
ProjectVariables
ProjectDeployTokens
PushRules
Releases
ReleaseLinks
Repositories
RepositoryFiles
RepositorySubmodules
Runners
Services
Tags
Todos
Triggers
VulnerabilityFindings

// Everything
Gitlab

Examples

Once you have your library instantiated, you can utilize many of the API's functionality:

Using the await/async method

import { Gitlab } from '@gitbeaker/node';

const api = new Gitlab({
  host: 'https://example.com',
  token: 'personaltoken',
});

// Listing users
let users = await api.Users.all();

// Or using Promise-Then notation
api.Projects.all().then((projects) => {
  console.log(projects);
});

A general rule about all the function parameters:

  • If it's a required parameter, it is a named argument in the functions
  • If it's an optional parameter, it is defined in a options object following the named arguments

ie.

import { Gitlab } from '@gitbeaker/node';

const api = new Gitlab({
  host: 'https://example.com',
  token: 'personaltoken',
});

api.Projects.create({
  //options defined in the Gitlab API documentation
});

Pagination

Available pagination options:

Name Keyset Offset Type Default Description
pagination X X 'offset' or 'keyset' 'offset' Defines which pagination type should be used
perPage X X Number 20 Amount of results per request
maxPages X X Number N/A Maximum amount of requests that should be made
page X Number N/A Specific page to be retrieved
showExpanded X Boolean false Returns with the pagination information in addition to the data

Offset Pagination

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 itself can take a while to be fulfilled. As such, a maxPages option can be passed to limit the scope of the all function.

import { Gitlab } from 'gitlab';

const api = new Gitlab({
  host: 'https://example.com',
  token: 'personaltoken',
});

let projects = await api.Projects.all({ maxPages: 2 });

You can also use this in conjunction with the perPage argument which would override the default of 30 per page set by Gitlab:

import { Gitlab } from 'gitlab';

const api = new Gitlab({
  host: 'https://example.com',
  token: 'personaltoken',
});

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 option showExpanded. If there are multiple results the pagination property will be included as shown below:

...
const { data, paginationInfo } = await api.Projects.all({
  perPage:40,
  maxPages:2,
  showExpanded: true
});
...

This will result in a response in this format:

data: [
...
],
paginationInfo: {
  next: 4,
  current: 2,
  previous: 1,
  perPage: 3,
}

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.

Keyset Pagination

Similarly, support for Keyset pagination can be toggled on by passing a pagination parameter as a query option

const { data } = await api.Projects.all({
  pagination: 'keyset',
});

Note that for keyset pagination, page, and showExpanded are not supported.

Sudo

For private gitlab instances, administrators can 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:

import { NotificationSettings } from 'gitlab';

const service = new NotificationSettings({
  host:   'https://example.com',
  token: 'personaltoken'
  sudo: 8 // Can be the user ID or a username
});

await service.edit({
  level: NotificationSettings.LEVELS.DISABLED
})

Custom Request Libraries

There is another constructor parameter that allows the user to specify their 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 file

import { Gitlab } from 'gitlab';
import YourCustomRequester from 'custom-requester';

const api = new Gitlab({
  host: 'https://example.com',
  token: 'personaltoken',
  requester: YourCustomRequester,
});

Misc

Handling HTTPS certificates

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:

"scripts": {
    "start": "NODE_EXTRA_CA_CERTS=./secrets/3ShapeCA.pem node bot.js"
},

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.

Non JSON/Text Responses

For responses such as file data that may be returned from the API, the data is exposed as a buffer. For example, when trying to write a file, this can be done like:

let bufferedData = await api.Jobs.downloadLatestArtifactFile(project.id, 'test', 'job_test');

fs.writeFileSync('test.zip', bufferedData);

Debugging

Depending on the library used, the full information about the request error can be a bit obfuscated. Ideally, the entire information is returned from Ky (browser) or Got (nodejs) however for simplicity, a description property is added to the error object that has the error message attached. Simply look for e.description to have a better idea of what the error actually is.

Testing

Testing is a work-in-progress right now but here is the start.

Unit Tests

Run:

yarn test:unit

Integration Tests

  1. First, run Gitlab in a docker container:
docker-compose -f scripts/docker-compose.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:
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}"')
  1. Now run the tests
yarn test:integration:node

You can also define them in front of the yarn script

PERSONAL_ACCESS_TOKEN='abcdefg' GITLAB_URL='https://localhost:8080' yarn test

Note it may take about 3 minutes to get the variables while Gitlab is starting up in the container

Contributors

This started as a fork from node-gitlab-legacy but I ended up rewriting much of the code. Here are the original work's contributors.


Justin Dalrymple

πŸ’» πŸ‘€ 🚧 πŸ› πŸ€” πŸ“– ⚠️ πŸš‡

akira345

πŸ“– πŸ‘€ πŸ’»

Pavel Birukov

πŸ‘€ πŸ’»

Joseph Petersen

πŸ‘€ πŸ€” πŸ› πŸ’»

Louis Cherel

πŸ‘€ πŸ’»

Adam Dehnel

πŸ‘€ 🚧 πŸ› πŸ’»

Ev Haus

πŸ‘€ πŸ’»

LoΓ―c Mahieu

πŸ‘€

Giuseppe Angri

πŸ‘€ πŸ’»

jennparise

πŸ‘€ πŸ› πŸ’»

Oscar

πŸ‘€

Daniel Ruf

πŸ‘€ πŸ“– πŸ› 🚧 πŸ’»

schindld

πŸ‘€ πŸ’»

Alvaro

πŸ’»

Daniel Moore

πŸ’»

Dylan M. Taylor

πŸ“– πŸ’»

Corentin Mors

πŸ’»

xatavian

πŸ’»

Yevgeny Petukhov

πŸ’»

MickaΓ«l Tricot

πŸ“–

Andrea

πŸ’»

Flavien Bridault

⚠️ πŸ’»

s-kazuki

πŸ’»

Kipras Melnikovas

πŸ’»

xieyu

πŸ’»

st1gok

πŸ’»

Max Wittig

πŸ“– ⚠️ πŸ’»

Niklas Lochschmidt

πŸ“– ⚠️ πŸ’»

Ilya Dus

πŸ’»

Omar Awamry

πŸ’»

Hennadii Varava

πŸ’»

xiezht

πŸ“–

Martin Helmich

πŸ’»

Sean McGivern

πŸ“–

Clemens Lieb

πŸ’»

VojtΔ›ch Sajdl

⚠️ πŸ’»

divido

⚠️ πŸ’»

Vincent Boulaye

⚠️ πŸ’»

Aliyss Snow

πŸ“– ⚠️ πŸ’»

Mahmoud Saada

πŸ’»

Feng Yu

πŸ’»

Roy Jacobs

πŸ’»

Paul Lemke

πŸ’»

Ian Jenkins

⚠️ πŸ’»

nilennoct

⚠️ πŸ’»

Laffargue Michael

πŸ’»

Martin Howarth

⚠️ πŸ’»

pataar

πŸ’»

Ikko Ashimine

πŸ’» ⚠️

Bilal Aslam

πŸ’»

youngje

πŸ’»

Sullivan SENECHAL

πŸ’»

Felix Herold

πŸ’»

Sponsors

Special thanks for helping support this project:



About

🦊πŸ§ͺ A comprehensive and typed Gitlab SDK for Node.js, Browsers, Deno and CLI

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 98.8%
  • JavaScript 1.1%
  • Other 0.1%