node-gitlab-api

node-gitlab-api

GitLab API NodeJS library. It wraps the HTTP v4 API library described here.

Table of Contents

• Install
• Usage
  • Import
  • Examples
  • Pagination
• Docs
  • Projects
  • Groups
• Contributors
• Tests
• License
• Changelog

Install

# Install from npm
npm install node-gitlab-api

Usage

Import

ES6 (>=node 8.0.0)

URL to your GitLab instance should not include /api/v4 path.

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

const GitlabAPI = require('node-gitlab-api')({
  url:   'http://example.com', // Defaults to http://gitlab.com
  token: 'abcdefghij123456'	//Can be created in your profile. 
})

Or, use a OAuth token instead!

const GitlabAPI = require('node-gitlab-api')({
  url:   'http://example.com', // Defaults to http://gitlab.com
  oauthToken: 'abcdefghij123456'
})

ES5

The same parameters as above, but the require url inclues a /dist/es5:

const GitlabAPI = require('node-gitlab-api/dist/es5')({
  ...
})

Examples

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

Using the await/async method

// Listing users
let users = await GitlabAPI.users.all();

Or using Promise-Then notation

// Listing projects
GitlabAPI.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.

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

// Listing projects
let projects = await GitlabAPI.projects.all({max_pages:2});

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

// Listing projects
let projects = await GitlabAPI.projects.all({max_pages:2, per_page:40});

Docs

Although there are the official docs for the API, below are some additional docs for this node package! Would eventually like to document everything, but there is quite a bit to document. PR's are welcome! 😎

• Projects
• Groups

Tests

Nothing yet, but its on the TODO list :P

Contributors

This started off as a fork from node-gitlab but I ended up rewriting 90% 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

License

MIT

Changelog

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-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": "<path-to-your-clone>"
    ...
  }

Changelog

2.2.7 (2018-3-15)

• Fixing babel runtime