@nerdvision/gitlab-js

A more intuitive and modern way to interact with the GitLab API in JavaScript. This library aims to abstract out the GitLab API and unify its usage across common use cases. It also aims to fully support types for all arguments and returned data.

This library is in alpha and there may be breaking changes & parts that are not functional. It is not feature complete yet and is missing many of the GitLab API routes.

Need some functionality that we haven't implemented yet? Make an issue or implement it yourself and make a merge request!

Installation & set up

Install the package:

npm i @nerdvision/gitlab-js

Initialise it with your GitLab token or without anything to use the API anonymously:

import {Client} from '@nerdvision/gitlab-js';

const client = new Client();
const authedClient = new Client('your-token-here');

Using a privately hosted version of GitLab? Just specify the host in the config:

const client = new Client({
  token: 'your-token-here',
  host: 'https://gitlab.mysite.com',
});

Don't want to specify the arguments in code? The library defaults to the value of GITLAB_TOKEN and GITLAB_HOST if you don't pass in an option for them.

Now you can start using the library!

const projects = await client.projects.list();

General usage

Everything in the project comes from the base client we've initialised above. When you request something, the context is kept so you only need to query for the new data.

E.G. if you wanted to grab all projects inside the group nerd-vision/opensource, you could use the following code:

const group = await client.groups.find('nerd-vision/opensource');
const projects = await group.projects.list();

Cool! We've got a list of projects in that group. Let's now grab all the open issues in the first project in the list:

const project = projects[0];
const issues = await project.issues.list({state: 'opened'});

We've now very easily pulled a list of all open issues in the first project in the nerd-vision/opensource group!

Most available APIs in this project inherit one of the following classes, ensuring a consistent developing experience across all of your GitLab API usage.

Collections

Collections of items handle access routes that return multiple of the same item. There are a few options available to you for accessing collections. All of these methods return promises.

• .list(query = {})

Query GitLab for a list of items that match the optional query.

Example:

const allIssues = await project.issues.list();
const openIssues = await project.issues.list({state: 'opened'});

• .find(id: string | number, query = {})

Find a single item in the list by its numerical id or slug. You can also specify an optional query to only return the item if it fulfills the given query.

Example:

const groupFromId = await client.groups.find(10697584);
const groupFromSlug = await client.groups.find('nerd-vision/opensource');

• .save(item)

Save the given item into the collection. This can either be an existing instance of the item, or an object with the data that you're looking to save. If the item has an ID (or iid), it will attempt to send an update request, else it will attempt to save a new instance

Example:

await client.groups.save({name: 'my-new-group'}); // creates a new group
await client.groups.save({id: 123, name: 'my-new-group'}); // updates an existing group with the id 123

Items

Items store data and allow you to access relations of that item.

• .data

Access the data for the item. This is currently the raw response from GitLab.

Singular items

Singular items are items that do not live inside collections. E.G. A pipeline job can only ever have one trace associated with it, so trace is a singular item instead of a collection of traces.

Available APIs

Key

• C - Collection
• I - Item
• S - Singular item
• M - Callable method to do said action

API tree

• client
  • groups - C
  • projects - C
  • issues - C
  • mergeRequests - C
  • epics - C
  • users - C

Links between endpoints

• group - I

  • projects - C
  • epics - C
  • boards - C
  • milestones - C
  • issues - C
  • mergeRequests - C

• project - I

  • issues - C
  • mergeRequests - C
  • boards - C
  • branches - C
  • tags - C
  • pipelines - C
  • jobs - C
  • releases - C
  • commits - C

• mergeRequest - I

  • toggleDraft - M
  • approve - M
  • unapprove - M
  • approvals - S
  • discussions - C
  • notes - C

• issue - I

  • discussions - C
  • notes - C

• epic - I

  • issues - C
  • discussions - C
  • notes - C

• job - I

  • trace - M

• pipeline - I

  • jobs - C

Types

The library was built with Typescript and includes types for all the method usages and implemented APIs. Return/query parameters are not fully implemented yet.

Need some help?

If you need some help with the library you can make an issue or join us on Discord and we'll be happy to assist!

Contributing

Many GitLab APIs are still missing from the library. If you're looking for something simple to get started with, this is a great place!

Merge requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

If you're looking for something else to contribute, take a look through our open issues.

Please make sure to update tests as appropriate.

License

Apache 2.0