A more intuitive and modern way to interact with the GitLab API in JavaScript
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!
Install the package:
``bash`
npm i @nerdvision/gitlab-js
Initialise it with your GitLab token or without anything to use the API
anonymously:
`javascript
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:
`javascript`
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!
`javascript`
const projects = await client.projects.list();
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:
`javascript`
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:
`javascript`
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 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:
`javascript`
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:
`javascript`
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:
`javascript`
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 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 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.
* C - Collection
* I - Item
* S - Singular item
* M - Callable method to do said action
* client
* groups - C
* projects - C
* issues - C
* mergeRequests - C
* epics - C
* users - C
* 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
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.
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!
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.