🤖 GitLab API NodeJS library with full support of all the Gitlab API services.
# Install from npm
npm install gitlab
The API's that are currently supported are:
// General
ApplicationSettings
BroadcastMessages
Events
FeatureFlags
GeoNodes
GitignoreTemplates
GitLabCIYMLTemplates
Keys
Licence
LicenceTemplates
Lint
Markdown
Namespaces
NotificationSettings
PagesDomains
Search
SidekiqMetrics
Snippets
SystemHooks
Version
Wikis
// Groups
Groups
GroupAccessRequests
GroupBadges
GroupCustomAttributes
GroupIssueBoards
GroupMembers
GroupMilestones
GroupProjects
GroupVariables
Epics
EpicIssues
EpicNotes
EpicDiscussions
// Projects
Branches
Commits
CommitDiscussions
ContainerRegistry
DeployKeys
Deployments
Environments
Issues
IssueAwardEmojis
IssueNotes
IssueDiscussions
Jobs
Labels
MergeRequests
MergeRequestAwardEmojis
MergeRequestDiscussions
MergeRequestNotes
Pipelines
PipelineSchedules
PipelineScheduleVariables
Projects
ProjectAccessRequests
ProjectBadges
ProjectCustomAttributes
ProjectImportExport
ProjectIssueBoards
ProjectHooks
ProjectMembers
ProjectMilestones
ProjectSnippets
ProjectSnippetNotes
ProjectSnippetDiscussions
ProjectSnippetAwardEmojis
ProtectedBranches
ProtectedTags
ProjectVariables
Releases
ReleaseLinks
Repositories
RepositoryFiles
Runners
Services
Tags
Triggers
// Users
Users
UserEmails
UserImpersonationTokens
UserKeys
UserGPGKeys
URL to your GitLab instance should not include /api/v4 path.
Instantiate the library using a basic token created in your Gitlab Profile
// ES6 (>=node 8.9.0)
import { Gitlab } from 'gitlab'; // All Resources
import { Projects } from 'gitlab'; // Just the Project Resource
//...etc
// ES5, assuming native or polyfilled Promise is available
const { Gitlab } = require('gitlab');
Instatiating options:
const api = new Gitlab({
host: 'http://gl.com', //Optional, Default: https://gitlab.com
token: 'personaltoken', //Personal Token. Required (one of the three tokens are required)
oauthToken: 'oauthtoken', //OAuth Token. Required (one of the three tokens are required)
jobToken: 'myJobToken', //CI job token. Required (one of the three tokens are required)
rejectUnauthorized: false //Http Certificate setting. Optional, Default: false
sudo: false //Sudo query parameter. Optional, Default: false
version = 'v4', //API Version ID. Optional, Default: v4
camelize = false, //Response Key Camelize. Camelizes all response body keys. Optional, Default: false
requester = KyRequester, //Request Library Wrapper. Optional, Default: Currently wraps Ky.
requestTimeout = 300000 //Request Library Timeout. Optional, Default: 300,000 milliseconds.
});
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.
import { ProjectsBundle } from 'gitlab';
const services = new ProjectsBundle({
host: 'http://example.com', // Defaults to https://gitlab.com
token: 'abcdefghij123456' // Can be created in your profile.
})
services.Projects.all()
services.MergeRequests.all()
etc..
Currently there are three Bundles:
Branches
Commits
CommitDiscussions
Deployments
DeployKeys
Environments
Issues
IssueNotes
IssueDiscussions
IssueAwardEmojis
Jobs
Labels
MergeRequests
MergeRequestAwardEmojis
MergeRequestDiscussions
MergeRequestNotes
Pipelines
PipelineSchedules
PipelineScheduleVariables
Projects
ProjectAccessRequests
ProjectBadges
ProjectCustomAttributes
ProjectImportExport
ProjectIssueBoards
ProjectHooks
ProjectMembers
ProjectMilestones
ProjectSnippets
ProjectSnippetNotes
ProjectSnippetDiscussions
ProjectSnippetAwardEmojis
ProtectedBranches
ProtectedTags
ProjectVariables
Repositories
RepositoryFiles
Runners
Services
Tags
Todos
Triggers
Users,
UserCustomAttributes,
UserEmails,
UserImpersonationTokens,
UserKeys,
UserGPGKeys
Groups
GroupAccessRequests
GroupBadges
GroupCustomAttributes
GroupIssueBoards
GroupMembers
GroupMilestones
GroupProjects
GroupVariables
Epics
EpicIssues
EpicNotes
EpicDiscussions
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"
},
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: '...',
token: '...',
rejectUnauthorized: false
})
NOTE: Using
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'will not work with thegitlablibrary. TherejectUnauthorizedkey is the only way to allow insecure certificates to be bypassed.
Once you have your library instantiated, you can utilize many of the API's functionality:
Using the await/async method
import { Gitlab } from 'gitlab';
const api = new Gitlab({
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);
});
General rule about all the function parameters:
ie.
import { Gitlab } from 'gitlab';
const api = new Gitlab({
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
});
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.
import { Gitlab } from 'gitlab';
const api = new Gitlab({
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 });
You can also use this in conjunction to the perPage argument which would override the default of 30 per page set by Gitlab:
import { Gitlab } from 'gitlab';
const api = new Gitlab({
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 });
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
maxPages or page properties.
...
const { data, pagination } = await api.Projects.all({
perPage:40,
maxPages:2,
showPagination: true
});
...
This will result in a response in this format:
data: [
...
],
pagination: {
total: 20,
next: 4,
current: 2,
previous: 1,
perPage: 3,
totalPages: 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.
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:
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 service.edit({
level: NotificationSettings.LEVELS.DISABLED
})
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 file
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
});
Although there are the official docs 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!!
To get this running locally rather than from your node_modules folder:
$ git clone https://github.com/jdalrymple/node-gitlab.git
$ cd node-gitlab
$ 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:
"dependencies": {
"gitlab": "5.0.0"
}
to this
"dependencies": {
"gitlab": "<path-to-your-clone>"
}
Testing is a work-in-progress right now but here is the start.
docker-compose -f docker-compose.test.yml up
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}"')
npm run test
# or, alternatively
npm run test-with-token # sets PERSONAL_ACCESS_TOKEN and GITLAB_URL from above, before running tests
You can also define them in front of the npm script
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
This started off as a fork from node-gitlab but I ended up rewriting much of the code. Here are the original work's contributors.
FAQs
Full NodeJS implementation of the GitLab API. Supports Promises, Async/Await.
The npm package gitlab receives a total of 83,328 weekly downloads. As such, gitlab popularity was classified as popular.
We found that gitlab demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.