repository·main·Indexed 23 days ago
https://github.com/jdalrymple/gitbeakerA comprehensive, typed GitLab SDK supporting Node.js, Deno, Bun, and browsers, providing complete coverage of GitLab APIs (up to version 16.5). The project includes @gitbeaker/rest for general use, @gitbeaker/core for API definitions, @gitbeaker/cli for terminal interaction, and @gitbeaker/requester-utils for creating custom SDK wrappers.
@gitbeaker/requester-utils is a utility package designed to help developers create custom wrappers around the @gitbeaker/core GitLab SDK. It provides foundational classes like RequesterUtils and BaseResource to streamline the creation of specialized GitLab API wrappers.Gitbeaker is distributed as several specialized packages. Depending on your needs, you should choose the appropriate package:
fetch.@gitbeaker/rest distribution for terminal usage.Depending on your runtime environment, you can install or load @gitbeaker/requester-utils using the following methods:
Install via your preferred package manager:
npm install @gitbeaker/requester-utils
yarn add @gitbeaker/requester-utils
pnpm add @gitbeaker/requester-utilsThen import the utilities:
import { RequesterUtils, BaseResource } from '@gitbeaker/requester-utils';Load directly from esm.sh using the ?dts query parameter to include type definitions:
import { RequesterUtils, BaseResource } from 'https://esm.sh/@gitbeaker/requester-utils?dts';Load directly from esm.sh as an ES module:
<script type="module">
import { RequesterUtils, BaseResource } from 'https://esm.sh/@gitbeaker/requester-utils';
</script>import { RequesterUtils, BaseResource } from '@gitbeaker/requester-utils';If you want to run integration tests against a manually managed GitLab instance (instead of using the full test:full suite), follow these steps:
.docker directory and start the GitLab service.cd .docker && docker-compose up gitlabGITLAB_URL and GITLAB_PERSONAL_ACCESS_TOKEN environment variables.Default GitLab Credentials (for the containerized instance):
http://localhost:8080rootgitbeakersuperstrongpassword123# Step 1: Start GitLab
cd .docker && docker-compose up gitlab
# Step 2 & 3: Set env vars and run tests
export GITLAB_URL="http://localhost:8080"
export GITLAB_PERSONAL_ACCESS_TOKEN="superstrongpassword123"
pnpm test:integrationThe @gitbeaker/core package is the core SDK for the GitLab API. Note that it is not intended for direct use; developers should instead use @gitbeaker/rest or @gitbeaker/cli.
Depending on your runtime, you can load the package as follows:
Install via npm, yarn, or pnpm:
npm install @gitbeaker/core
yarn add @gitbeaker/core
pnpm add @gitbeaker/coreThen import the Gitlab class:
import { Gitlab } from '@gitbeaker/core';Load directly from esm.sh:
import { Gitlab } from 'https://esm.sh/@gitbeaker/core?dts';Load directly from esm.sh using a module script:
<script type="module">
import { Gitlab } from 'https://esm.sh/@gitbeaker/core';
</script>import { Gitlab } from '@gitbeaker/core';If your GitLab server uses HTTPS with custom certificates, the recommended approach is to use the NODE_EXTRA_CA_CERTS environment variable to point to your certificate file.
Warning: You can bypass certificate validation by setting process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0', but this is insecure and should be avoided.
"scripts": {
"start": "NODE_EXTRA_CA_CERTS=./secrets/3ShapeCA.pem node bot.js"
},The @gitbeaker/cli is a CLI wrapper for the @gitbeaker/rest SDK. You can install it globally using npm, yarn, or pnpm. Requires Node 18+.
npm install -g @gitbeaker/cli
yarn add -g @gitbeaker/cli
pnpm add -g @gitbeaker/cliGitbeaker relies on fetch support. Since native fetch is standard in Node 18+, users on Node v16.18+ can enable compatibility by installing node-fetch and polyfilling the global fetch object in their application's entry point.
const semver = require('semver');
if (semver.lt(process.version, '20.0.0')) {
global.fetch = require('node-fetch');
}The CLI follows a specific command structure to interact with the GitLab API services. You can use either the full gitbeaker command or the shorthand gb.
gitbeaker [service name] [method name] --config_args pos_arg1 pos_argN --opts_arg1 --opts_argN
service name: Any supported API name from the @gitbeaker/rest SDK.method name: Any supported command on that API service (e.g., all, show, remove, update).--config_args: General configuration arguments (like personal tokens). These must include a gb or gl prefix (e.g., --gb-token).pos_arg1 ... pos_argN: Positional arguments required by the method. These must be provided in the correct order. They can also be provided as flags (e.g., --pos_arg1), but order must be preserved.--opts_arg1 ... --opts_argN: Optional arguments as defined by the GitLab API documentation.# To get all the projects
gitbeaker projects all --gb-token="personaltoken"
# To get all the projects id=2 and optional parameter "search" = "cool"
gitbeaker projects all --gb-token="personaltoken" 2 --search="cool"The recommended way to run the complete test suite (types, unit, integration, and e2e) is using the containerized approach. This starts a GitLab CE instance via Docker Compose, waits for it to be healthy, sets environment variables, and runs all tests sequentially.
Prerequisites:
pnpm test:fullYou can run specific subsets of the test suite using the following commands:
pnpm test:typespnpm test:unitpnpm test:integration (requires a running GitLab instance)pnpm test:e2e# Type tests only
pnpm test:types
# Unit tests only
pnpm test:unit
# Integration tests only (requires GitLab running)
pnpm test:integration
# End-to-end tests only
pnpm test:e2e