Negligible Psychological Misery
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    gitlabpublic

    npm npm dependencies Status devDependencies Status Greenkeeper badge Code Climate codecov License: MIT

    node-gitlab

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

    Table of Contents

    Install

    # Install from npm 
    npm install gitlab

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

    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 'gitlab';
     
    // ES5
    const Gitlab = require('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'
    })
     

    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 'gitlab';
     
    const service = new Projects({
      url:   'http://example.com', // Defaults to http://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 '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:

    1. ProjectsBundle which includes:
    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
    
    1. UsersBundle which includes:
    Users,
    UserCustomAttributes,
    UserEmails,
    UserImpersonationTokens,
    UserKeys,
    UserGPGKeys
    
    1. GroupsBundle which includes:
    Groups
    GroupAccessRequests
    GroupBadges
    GroupCustomAttributes
    GroupIssueBoards
    GroupMembers
    GroupMilestones
    GroupProjects
    GroupVariables
    Epics
    EpicIssues
    EpicNotes
    EpicDiscussions
    

    Using XMLHttpRequest

    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.

    Examples

    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:

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

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

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

    Development

    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>"
        ...
      }

    Testing

    Testing is a work-in-progress right now but here is the start.

    1. First run gitlab in a docker container:
    docker-compose -f docker-compose.test.yml up
    1. Once GitLab is up on localhost:8080, get the two environment variables from the docker image could either export them into environment variables locally:
      - 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}"')
    1. Now run the tests
    npm run test

    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

    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.

    License

    MIT

    Changelog

    3.4.0 (2018-5-24)

    • Added the first stage of testing in #71 with Adam Dehnel's guidence
    • Added jobs.show() that was missing from the Jobs service

    3.3.6 (2018-5-22)

    3.3.5 (2018-5-15)

    3.3.4 (2018-5-14)

    3.3.3 (2018-5-13)

    3.3.2 (2018-5-9)

    • Fixing #82
    • Fixing #83
    • Updating repo name for clarity

    3.3.0 (2018-5-7)

    3.2.2 (2018-5-2)

    • Fixed missing Version API

    3.2.1 (2018-4-23)

    • Fixed incorrectly named bundles

    3.2.0 (2018-4-21)

    3.1.1 (2018-4-17)

    • Fixed missing UserCustomAttributes export

    3.1.0 (2018-4-16)

    • Added addTimeEstimate, addTimeSpent, timeStats, resetTimeSpent and resetTimeEstimate to the Issues API. Requested in Issue #68
    • Added XMLHttpRequest Support PR #59

    Breaking Change

    • Renamed timeEstimate to addTimeEstimate, and timeSpend to addTimeSpent, in the MergeRequests API

    3.0.4 (2018-4-13)

    • Fixed endpoint for MergeRequestNotes thanks to Ev Haus in PR #63
    • Fixed Commits.editStatus method thanks to zhao0 in PR #65

    3.0.3 (2018-4-5)

    • Fixed the problem with the validation of Event resource options

    3.0.0 (2018-4-2)

    • Exporting all services seperatly ie. const { Projects } from 'gitlab'; as well as the usual default export: const Gitlab from 'gitlab'
    • 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-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)

    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)

    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

    install

    npm i gitlab

    Downloadsweekly downloads

    2,472

    version

    3.4.0

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar
    • avatar