node-gitlab-api

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

Table of Contents

• Install
• Usage
  • Supported APIs
  • Import
    • Specific Imports
    • Bundle Imports
  • Examples
  • Pagination
• Migrating from node-gitlab
• Docs
  • Projects
  • Groups
• Contributors
• Tests
• License
• Changelog

Install

# Install from npm
npm install node-gitlab-api

Usage

Supported APIs

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
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
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

Import

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 'node-gitlab-api';

// ES5
const Gitlab = require('node-gitlab-api/dist/es5').default


// Instantiating
const api = new Gitlab({
  url:   'https://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:   'https://example.com', // Defaults to https://gitlab.com
  oauthToken: 'abcdefghij123456'
})

Specific Imports

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 'node-gitlab-api';

const service = new Projects({
  url:   'https://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 convience, there is a Bundle export for importing and instantiating all these related API's at once.

import { ProjectsBundle } from 'node-gitlab-api';

const services = new ProjectsBundle({
  url:   'https://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:

1. ProjectsBundle which includes:

Branches
Commits
Deployments
DeployKeys
Environments
Issues
IssueNotes
IssueDiscussions
IssueAwardEmojis
Jobs
Labels
MergeRequests
MergeRequestAwardEmojis
MergeRequestNotes
Pipelines
PipelineSchedules
PipelineScheduleVariables
Projects
ProjectAccessRequests
ProjectCustomAttributes
ProjectImportExport
ProjectIssueBoards
ProjectHooks
ProjectMembers
ProjectMilestones
ProjectSnippets
ProjectSnippetNotes
ProjectSnippetDiscussions
ProjectSnippetAwardEmojis
ProtectedBranches
ProjectVariables
Repositories
RepositoryFiles
Runners
Services
Tags
Todos
Triggers

2. UsersBundle which includes:

Users,
UserEmails,
UserImpersonationTokens,
UserKeys,
UserGPGKeys

3. GroupsBundle which includes:

Groups
GroupAccessRequests
GroupBadges
GroupCustomAttributes
GroupIssueBoards
GroupMembers
GroupMilestones
GroupProjects
GroupVariables
Epics
EpicIssues
EpicNotes
EpicDiscussions

Examples

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

Using the await/async method

import Gitlab from 'node-gitlab-api';

const api = new Gitlab({
  url:   'https://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:

• 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.

import Gitlab from 'node-gitlab-api';

const api = new Gitlab({
  url:   'https://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
})

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 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 'node-gitlab-api';

const api = new Gitlab({
  url:   'https://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 'node-gitlab-api';

const api = new Gitlab({
  url:   'https://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});

Migrating from node-gitlab

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.

Docs

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!!

Tests

Nothing yet, but its on the TODO list 😛

Contributors

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.

• Dylan DesRosier
• Mike Wyatt
• Cory Zibeill
• Martin Bour
• Christoph Lehmann
• Frank V
• Salim Benabbou
• Tamás Török-Vistai
• Martin Benninger
• Adam Dehnel
• fewieden
• Jeff Pelton
• Claude Abounegm
• Stefan Hall
• Jordan Wallet

License

MIT

Changelog

3.0.0 (2018-4-2)

• Exporting all services seperatly ie. const { Projects } from 'node-gitlab-api'; as well as the usual default export: const Gitlab from 'node-gitlab-api'
• Exporting bunbles which are groups of related API's. These include: ProjectsBundle, UsersBundle and GroupsBundle
• Added events support to the Projects, and Users
• Added full support for ProjectVariables and GroupVariables
• Added support for Events. This is also exposed in Projects and Users under the events function
• Fixed the missing options parameter for the ProjectMembers and GroupMemebers APIs in PR [#45] thanks to Stefan Hall
• Supporting both camelCase and snake_case option properties: projects.all({perPage:5}) === projects.all({per_page: 5})
• Fixed problem with .all() functions where only the some of the results were being returned
• Completed support for all Gitlab APIs, #49, #53

Breaking Changes between 2.2.6 and 3.0.0

• Instantiation of the API must use the new operator consistently. See usage above.
• All services being exported are not capitalized for clarity that they are themselves api's and not properties. ie. Gitlab.Projects vs Gitlab.projects
• All subservices (services exposed as properties of other services) have been moved out into their own service

ProjectRepository -> Repositories, Tags, Commits, Branches and RepositoryFiles
Users -> Users, UserKeys, UserGPGKeys, UserCustomAttributes, UserVariables

• Moved createTodo function from MergeRequests API to Todos API
• Many services have been renamed:

ProjectProtectedBranches -> ProtectedBranches
ProjectDeployKeys -> DeployKeys
ProjectEnvironments -> Enviroments
ProjectJobs -> Jobs
ProjectLabels -> Labels
ProjectPipelines -> Pipelines
ProjectRepository -> Repositories
ProjectServices -> Services
ProjectTriggers -> Triggers

• Some services were merged:

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()

2.2.8 (2018-4-1)

• Updating babel

2.2.7 (2018-3-15)

• Fixing babel runtime

2.2.6 (2018-3-15)

• Fixed more issues within the url concatenation

2.2.5 (2018-3-15)

• Fixed #48 - Problem with trailing \ in url

2.2.4 (2018-2-12)

• Fixing babel runtime

2.2.6 (2018-3-15)

• Fixed more issues within the url concatenation

2.2.5 (2018-3-15)

• Fixed #48 - Problem with trailing \ in url

2.2.4 (2018-2-3)

• Fixed #33 - Bug within the es5 transpilling configuration
• Fixed the missing options for tags.all #40
• Added delete key method to UserKeys.js #41 thanks to Claude Abounegm

2.2.3 (2018-2-3)

• Fixed #37 - Bug within the customAttributes logic

2.2.2 (2018-1-24)

• Fixing bug with the version support

2.2.1 (2018-1-23)

• Added support for the Version API through version.show()

2.2.0 (2018-1-18)

• Fixed the missing options parameter for the ProjectRepositoryCommitComment's model thanks to Martin Benninger in PR #21
• Removal of the left over debug console.logs's within project issues again by Martin Benninger in PR #21
• Added proper docs for ProjectRepositoryFiles, enabled default urlEncoding for the passed in file paths and also documented how to run locally via npm linking for Development testing thanks to Adam Dehnel in PR #23
• Exposed the Merge Requests resource which was missing from the exports list thanks to fewieden in PR #26
• Added support for the Project Enviroments API and the Project Jobs API thanks to Jeff Pelton in PR #28
• Fixing parse function to handle encoded urls that don't include '/' such as in groups #24

Breaking Changes between 2.1.0 and 2.2.0

• Fixed a problem with the get responses where the response contained the full request response and not just the body

2.1.0 (2017-12-15)

• Added es5 support and clarified the default supported versions of node (>=8.0.0 for default)
• Updating project docs for consistency
• Adding project unsharing to API. It was in the docs, but missing from the API
• Updating deprecated protected branches endpoint. Previously this was projects.branches.protect now its projects.protectedBranches.protect
• Added Owned Runners and Runner Jobs API

Breaking Changes between 1.3.3 and 2.1.0

• The list functions are no longer supported and have all been renamed to all
• The update functions are no longer supported and have all been renamed to edit
• The addKey function has been renamed to add in UserKeys class
• The deploy_keys and merge_requests properties have been renamed to deployKeys and mergeRequests
• Removed old group member functions from the groups class as they have been moved to the GroupMembers class. This includes the addMember, listMembers, editMember, and removeMember. These functions can now be access via group.members.add, group.members.all, group.members.edit and group.members.remove respectively.
• Removed the old group project functions from the Group class. These are now located in the GroupProject class. The functions that have been removed are listProjects, addProjects. These functions can be access by group.projects.all, and group.projects.add respectively.
• Updated the structure of the ProjectRepository class such that its commits, branches, tags and files are properties and can be accessed like repository.commits.all() etc.
• Removed unused labels endpoint since it already exists under projects.labels

2.0.1-rc.1 (2017-11-29)

• Updating pagination changes into v2.0.1
• Removed unused labels endpoint since it already exists under projects.labels
• Added a mergeRequests class for the merge_requests endpoints
• Extended the ProjectMergeRequests class for additional functionality that was missing for project merge requests such as accepting merge requests, cancelling merges when the pipeline succeeds, listing issues that will close on merge, subscribing/unsubscribing to merges, creating todos, time spent and time estimates as well as time stats.
• Fixed the notes endpoints for ProjectMergeRequests. This can now be access via projects.mergeRequests.notes.[command here]
• Added comments endpoints to the ProjectRepositoryCommits class
• Added the ability to post a status to a specific commit to the Project class

1.3.3 (2017-11-29)

• Adding pagination to project pipelines thanks to Tamás Török-Vistai

2.0.0-rc.2 (2017-11-28)

• Updating all recent core changes into v2.0.0

1.3.2 (2017-11-28)

• Adding default values for the BaseModel options parameter.

1.3.1 (2017-11-27)

• Fixed broken argument reference in the showFile and showFileRaw functions.

2.0.0-rc.1 (2017-11-25)

• Updated project docs for clarity
• Cleaned up many linting problems within the class models
• Removed mutator operations on the options arguments
• Renamed ProjectKeys to ProjectDeployKeys
• Renamed list functions to all for consistency
• Renamed update functions to edit for consistency
• Renaming addKey just to add in UserKeys class
• Renaming deploy_keys and merge_requests to deployKeys and mergeRequests for consistency
• Adding Project Access Requests
• Removing old group member functions from the groups class as they have been moved to the GroupMembers class. This includes the addMember, listMembers, editMember, and removeMember. These functions can now be access via group.members.add, group.members.all, group.members.edit and group.members.remove respectively.
• Removed the old group project functions from the Group class. These are now located in the GroupProject class. The functions that have been removed are listProjects, addProjects. These functions can be access by group.projects.all, and group.projects.add respectively.
• Methods in the ProjectDeployKeys class updated for consistency
• Methods in the ProjectHooks updated for consistency
• Updated the structure of the ProjectRepository class with commits, branches, tags and files properties.
• Added contributors, showBlob and showBlobRaw functions to the ProjectRepository class

1.3.0 (2017-11-25)

• Extending the Groups API, see docs for a full overview.

1.2.0 (2017-11-25)

• Adding fix to the API constructor to include the missing oauthToken thanks to Salim Benabbou.
• Updated some of the outdated gitlab repository file endpoints outlined in Issue #11: showFile, updateFile, and createFile. Also added deleteFile and showRawFile.
• Fixing bug where many pages where attempted to be loaded on every GET request.

1.1.4 (2017-11-17)

• Library maintenance, cleaning up spelling errors, updating dependencies, adding to contributors lists etc.

1.1.3 (2017-11-17)

• Fixing typos in the project sharing (group_access) thanks to Christoph Lehmann
• Updated the ReadMe to be more clear based on suggestions from Frank V

1.1.2 (2017-10-29)

• Updated the protected branch functionality by adding an options parameter originally proposed by Martin Bour
• Removed old paging logic from groups
• Updating library dependencies

1.1.1 (2017-09-24)

• Patch, fixed a broken pagination property
• Adding in missing options parameter in the groups API thanks to a pull request from Cory Zibell

1.1.0 (2017-09-24)

• Adding proper pagination support thanks to a problem noticed by Mike Wyatt

1.0.14 (2017-08-1)

• Adding default file name for file uploads. If none is supplied, the file name is inferred from the file path

1.0.13 (2017-07-31)

• Fixed another bug in the project file upload functionality

1.0.12 (2017-07-30)

• Added issue links (for related issues)
• Fixed project file upload

1.0.11 (2017-07-20)

• Fixing the problem where Id was used instead of IId's for Project issues
• Fixing the naming convention for Project Issues
• Standardized the use of parseInt in the code base
• Removed instances of duplicate code found by code climate

1.0.10 (2017-07-13)

• Fixing Issues #1, #2, and #3

1.0.9 (2017-07-06)

• Fixing broken Notes API reference
• Added Project triggers, members and hooks docs
• Moved Project Runners into its own scope and separated out general Runners API logic

1.0.8 (2017-06-30)

• Adding more to the Project Issue Notes API
• Updating Readme to show examples of connecting with OAuth tokens
• Begun adding documentation for projects

1.0.7 (2017-06-23)

• Fixing bug within the Issues API; reference to an old function.

1.0.6 (2017-06-23)

• Fixing bug within the Labels API; Missing required argument.

1.0.5 (2017-06-23)

• Fixing bug within the delete API calls. It was missing query parameters

1.0.4 (2017-06-23)

• Adding more to the Labels API
• Cleaned up the Issues class

1.0.3 (2017-06-23)

• Updating problems within the Milestone API
• Removed the old 'list' calls for projects and issues which displayed a deprecated message. Only all is available now.

1.0.2 (2017-06-22)

• Updating examples in ReadMe
• Adding dependency badges
• Removing unused test files

1.0.1 (2017-06-21)

• Initial release
• TODO: Tests, Examples

Development

To get this running locally rather than from your node_modules folder:

$ git clone https://github.com/jdalrymple/node-gitlab-api.git
$ cd node-gitlab-api
$ npm install
$ npm build

And then inside whatever project you are using node-gitlab-api in you change your references to use that repo. In your package.json of that upstream project change:

  "dependencies": {
    ...
    "node-gitlab-api": "2.1.0"
    ...
  }

to this

  "dependencies": {
    ...
    "node-gitlab-api": ""
    ...
  }