node-gitlab-api

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

Table of Contents

• Install
• Usage
• Docs
  • Projects
  • Groups
• Contributors
• License
• Changelog

Install

# Install from npm
npm install node-gitlab-api

Usage

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'
})

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!

• Projects

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

License

MIT

Changelog

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.

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