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
Namespaces
NotificationSettings
PagesDomains
Search
SidekiqMetrics
SystemHooks
Version
Wikis
// Groups
Groups
GroupAccessRequests
GroupBadges
GroupCustomAttributes
GroupIssueBoards
GroupMembers
GroupMilestones
GroupProjects
GroupVariables
Epics
EpicIssues
EpicNotes
EpicDiscussions
// Projects
Branches
Commits
Deployments
DeployKeys
Environments
Issues
IssueNotes
IssueDiscussions
IssueAwardEmojis
Jobs
Labels
MergeRequests
MergeRequestAwardEmojis
MergeRequestNotes
Pipelines
PipelineSchedules
PipelineScheduleVariables
Projects
ProjectAccessRequests
ProjectBadges
ProjectCustomAttributes
ProjectImportExport
ProjectIssueBoards
ProjectHooks
ProjectMembers
ProjectMilestones
ProjectSnippets
ProjectSnippetNotes
ProjectSnippetDiscussions
ProjectSnippetAwardEmojis
ProtectedBranches
ProjectVariables
Repositories
RepositoryFiles
Runners
Services
Tags
Todos
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.0.0)
import Gitlab from 'gitlab';
// ES5
const Gitlab = require('node-gitlab/dist/es5').default
// Instantiating
const api = new Gitlab({
url: 'http://example.com', // Defaults to http://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'
})
Sometimes you dont want to import and instantiate the whole gitlab api, perhaps you only want access to the Projects API. To do this, one only needs to import and instantiate this specific API:
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.
})
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 convience, there is a Bundle export for importing and instantiating all these related API's at once.
import { ProjectsBundle } from 'gitlab';
const services = new ProjectsBundle({
url: 'http://example.com', // Defaults to http://gitlab.com
token: 'abcdefghij123456' // Can be created in your profile.
})
services.Projects.all()
services.MergeRequests.all()
etc..
Currently there are three Bundles:
Branches
Commits
Deployments
DeployKeys
Environments
Issues
IssueNotes
IssueDiscussions
IssueAwardEmojis
Jobs
Labels
MergeRequests
MergeRequestAwardEmojis
MergeRequestNotes
Pipelines
PipelineSchedules
PipelineScheduleVariables
Projects
ProjectAccessRequests
ProjectBadges
ProjectCustomAttributes
ProjectImportExport
ProjectIssueBoards
ProjectHooks
ProjectMembers
ProjectMilestones
ProjectSnippets
ProjectSnippetNotes
ProjectSnippetDiscussions
ProjectSnippetAwardEmojis
ProtectedBranches
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
This package uses the 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:
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.
useXMLHttpRequest: true // Use the browser's XMLHttpRequest instead of Node's Request library
})
WARNING: Currently this option does not support the multipart/form-data content type, and therefore the endpoint for uploading a file to a project will not work correctly. All other endpoints should work exactly as expected.
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({
url: 'http://example.com', // Defaults to http://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({
url: 'http://example.com', // Defaults to http://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({
url: 'http://example.com', // Defaults to http://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({
url: 'http://example.com', // Defaults to http://gitlab.com
token: 'abcdefghij123456' // Can be created in your profile.
});
let projects = await api.Projects.all({maxPages:2, perPage:40});
With the sucess 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 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 transisition, but if there is anything that you're having trouble with please feel free to create an issue! If not myself, someone will definitly have the answer to help get you all setup up as quickly as possible.
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 documention for these goodies [#39]! Stay tuned!!
Nothing yet, but its on the TODO list :P
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": {
...
"node-gitlab": "2.1.0"
...
}
to this
"dependencies": {
...
"node-gitlab": "<path-to-your-clone>"
...
}
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.
Breaking Change
projects.all({perPage:5}) === projects.all({per_page: 5})ProjectRepository -> Repositories, Tags, Commits, Branches and RepositoryFiles
Users -> Users, UserKeys, UserGPGKeys, UserCustomAttributes, UserVariables
ProjectProtectedBranches -> ProtectedBranches
ProjectDeployKeys -> DeployKeys
ProjectEnvironments -> Enviroments
ProjectJobs -> Jobs
ProjectLabels -> Labels
ProjectPipelines -> Pipelines
ProjectRepository -> Repositories
ProjectServices -> Services
ProjectTriggers -> Triggers
Issues = ProjectIssues + Issues. ProjectId is optional for all()
MergeRequests = ProjectMergeRequests + MergeRequests + MergeRequestsChanges + MergeRequestsCommits + MergeRequestVersions. ProjectId is optional for all()
Runners = ProjectRunners + Runners. ProjectId is optional for all()
\ in urlprojects.branches.protect now its projects.protectedBranches.protectlist functions are no longer supported and have all been renamed to allupdate functions are no longer supported and have all been renamed to editaddKey function has been renamed to add in UserKeys classrepository.commits.all() etc.list functions to all for consistencyupdate functions to edit for consistency3.3.5 (2018-5-15)
FAQs
Full NodeJS implementation of the GitLab API. Supports Promises, Async/Await.
The npm package gitlab receives a total of 75,163 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.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."