Gitlab-client-api is a client api for the gitlab api (v4). It provides methods for all of the following:
- [x] Projects
- [x] Branches
- [x] Groups
- [x] Users
- [x] Issues
- [x] Merge Requests
- [x] Commits
- [x] Pipelines
- [x] Jobs
- [x] Files
npm install gitlab-client-api
yarn add gitlab-client-api
import { Gitlab } from "gitlab-client-api";
// Create a new instance of the gitlab client
// Either set the private token as options of provide env variable GITLAB_TOKEN
// Setting cache to true will cache the results of requests that were made with that instance of the client
const gitlab = new Gitlab({
privateToken: "your-private-token",
gitlabUrl: "https://subdomain.gitlab.com", // default is https://gitlab.com
cache: true, // default is false
});
// Cache can be cleared with
gitlab.resetCache();
Find users search Options: UserSearchOptions
User Object interface:
// find users
const users = await gitlab.findUsers({ username: "Hamza-bouhelal" });
// find user associated with the private token
const user = await gitlab.getUser();
Find groups search Options: GroupSearchOptions
Group Object interface: GroupInfo
Create Group Options: CreateGroupOptions
// gets all groups matching the search term
const groups = await gitlab.findGroups({ search: "gitlab" });
console.log(groups[0]?.name);
// create new group
const newGroup = await gitlab.createGroup({ name: "test", path: "test" });
// delete group
await newGroup.delete();
Find projects search Options: ProjectSearchOptions
Project Object interface: ProjectInfo
Create Project Options: CreateProjectOptions
// gets all projects matching the search term
const projects = await gitlab.findProjects({ search: "gitlab-client-api" });
console.log(projects[0]?.id);
// create new project
const newProject = await gitlab.createProject({ name: "test" });
console.log(newProject.id);
// archive project
await newProject.archive();
// unarchive project
await newProject.unarchive();
// delete project
await newProject.delete();
Find Issue search Options: IssueSearchOptions
Issue Object interface: IssueInfo
New Issue Options: CreateIssueOptions
// find issues in project
const issues = await myProject.findIssues();
console.log(issues[0]?.author);
// create a new issue
const newIssue = await myProject.createIssue({
title: "New Issue",
description: "This is a new issue",
});
// delete an issue
await newIssue.delete();
File Object interface: FileInfo
// Get file in project
const file = await myProject.getFile("/test.txt", "master");
console.log(file.content);
// get file blame
const blame = await file.getBlame();
Find Merge Request search Options: MergeRequestSearchOptions
Merge Request Object interface: MergeRequestInfo
New Merge Request Options: CreateMergeRequestOptions
// get all merge requests of a project
const mergeRequests = await project.findMergeRequests({
search: "my-merge-request-title",
});
console.log(mergeRequests[0]?.author);
// create a new merge request
const newMergeRequest = await someBranch.createMergeRequest({
target_branch: "master",
title: "New Merge Request",
});
// accept and merge a merge request
await newMergeRequest.merge();
// delete a merge request
await newMergeRequest.delete();
Find Branch search Options: BranchSearchOptions
Branch Object interface: BranchInfo
// get all branches of a project
const branches = await project.findBranches();
console.log(branches[0]?.name);
// get branch from a found pipeline
const branchFromPipeline = await pipeline.getBranch();
console.log(branchFromPipeline.name);
// create a new branch
const newBranch = await project.createBranch("new-branch", "master");
// delete a branch
// WARNING: This will delete the branch and all of its commits
await newBranch.delete();
Find Commit search Options: CommitSearchOptions
Commit Object interface: CommitInfo
// get commits of a project
const projectCommits = await project.findCommits({
author: "Hamza Bouhelal",
});
console.log(projectCommits[0]?.author_name);
// get commits of a branch
const masterBranchCommits = await masterBranch.findCommits();
console.log(masterBranchCommits[0]?.message);
// Revert a commit
// WARNING: This will create a new commit that reverts the original commit
const revertCommit = await projectCommits[0].revert();
Find Pipeline search Options: PipelineSearchOptions
Pipeline Object interface: PipelineInfo
// Find all pipelines for the project
const projectsPipelines = await myProject.findPipelines();
console.log(projectsPipelines[0]?.status);
// Find all pipelines for the merge request
const mergeRequestPipelines = await mergeRequest.findPipelines();
console.log(mergeRequestPipelines[0]?.status);
// Find all pipelines for the first commit
const commitPipelines = await projectCommits[0].findPipelines();
console.log(commitPipelines[0]?.status);
// Find all pipelines for the master branch
const masterBranchpipelines = await masterBranch.findPipelines();
console.log(masterBranchpipelines[0]?.status);
// Create a new pipeline for the master branch
const newPipeline = await masterBranch.createPipeline();
console.log(newPipeline.web_url);
// Retry a pipeline
const retriedPipeline = await newPipeline.retry();
// Cancel a pipeline
await retriedPipeline.cancel();
// Delete a pipeline
await retriedPipeline.delete();
Find Job search Options: JobSearchOptions
Job Object interface: JobInfo
const jobs = await pipeline.findJobs();
console.log(jobs[0]?.status);
// Download artifacts from a job
const buffer = await jobs[0].downloadArtifacts();
// Retry a job
const retriedJob = await jobs[0].retry();
// Cancel a job
await retriedJob.cancel();
// Erase a job
await retriedJob.erase();
// Start a job
await retriedJob.play();
Copyright (c) [2024] [Hamza Bouhelal]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.