tessl/npm-gitbeaker--rest

Cross Platform implementation of the GitLab API

Package Registries

Name: tessl/npm-gitbeaker--rest
Author: tessl

Support for multiple package registry types including npm, Maven, PyPI, NuGet, Composer, Conan, Helm, Go, RubyGems, and Debian packages.

Capabilities

Package Management

Generic package operations that work across all registry types.

/**
 * Packages resource class for generic package operations
 */
class Packages<C extends boolean = false> {
  /**
   * List all packages in a project
   * @param projectId - Project ID or path
   * @param options - Filter and pagination options
   * @returns Array of packages
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: AllPackagesOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<PackageSchema[], C, E, P>>;

  /**
   * Get details of a single package
   * @param projectId - Project ID
   * @param packageId - Package ID
   * @returns Package details
   */
  show<E extends boolean = false>(
    projectId: string | number,
    packageId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<PackageSchema, C, E, void>>;

  /**
   * Delete a package
   * @param projectId - Project ID
   * @param packageId - Package ID
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    packageId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

type AllPackagesOptions = {
  /** Order by field */
  orderBy?: 'created_at' | 'name' | 'version' | 'type';
  /** Sort direction */
  sort?: 'asc' | 'desc';
  /** Filter by package type */
  packageType?: 'npm' | 'maven' | 'pypi' | 'nuget' | 'composer' | 'conan' | 'helm' | 'golang' | 'rubygems' | 'debian';
  /** Filter by package name */
  packageName?: string;
  /** Include version-less packages */
  includeVersionless?: boolean;
  /** Filter by status */
  status?: 'default' | 'hidden';
};

Usage Examples:

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({ token: process.env.GITLAB_TOKEN });

// List all packages
const packages = await api.Packages.all(123);

// Filter by type
const npmPackages = await api.Packages.all(123, {
  packageType: 'npm',
  orderBy: 'created_at',
  sort: 'desc'
});

// Get package details
const package = await api.Packages.show(123, 456);

// Delete package
await api.Packages.remove(123, 456);

NPM Registry

Publish and manage npm packages.

/**
 * NPM resource class for npm package operations
 */
class NPM<C extends boolean = false> {
  /**
   * Publish an npm package
   * @param projectId - Project ID
   * @param packageName - Package name (scoped or unscoped)
   * @param packageVersion - Package version
   * @param file - Package tarball (.tgz file)
   * @returns Published package info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    packageName: string,
    packageVersion: string,
    file: Blob | Buffer,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

import * as fs from 'fs';

// Publish npm package
const packageTarball = fs.readFileSync('my-package-1.0.0.tgz');
await api.NPM.publishPackage(
  123,
  '@my-scope/my-package',
  '1.0.0',
  packageTarball
);

Configure npm client:

# Add to .npmrc
@my-scope:registry=https://gitlab.com/api/v4/projects/123/packages/npm/
//gitlab.com/api/v4/projects/123/packages/npm/:_authToken=${GITLAB_TOKEN}

Maven Registry

Publish and manage Maven artifacts.

/**
 * Maven resource class for Maven package operations
 */
class Maven<C extends boolean = false> {
  /**
   * Publish a Maven artifact
   * @param projectId - Project ID
   * @param groupId - Maven group ID
   * @param artifactId - Maven artifact ID
   * @param version - Artifact version
   * @param fileName - File name (e.g., 'my-app-1.0.0.jar')
   * @param file - Artifact file
   * @returns Published artifact info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    groupId: string,
    artifactId: string,
    version: string,
    fileName: string,
    file: Blob | Buffer,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

import * as fs from 'fs';

// Publish Maven artifact
const jarFile = fs.readFileSync('target/my-app-1.0.0.jar');
await api.Maven.publishPackage(
  123,
  'com.example',
  'my-app',
  '1.0.0',
  'my-app-1.0.0.jar',
  jarFile
);

Configure Maven settings.xml:

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Private-Token</name>
            <value>${env.GITLAB_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

PyPI Registry

Publish and manage Python packages.

/**
 * PyPI resource class for Python package operations
 */
class PyPI<C extends boolean = false> {
  /**
   * Publish a Python package
   * @param projectId - Project ID
   * @param file - Package file (wheel or source distribution)
   * @returns Published package info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    file: { content: Blob | Buffer; filename: string },
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

import * as fs from 'fs';

// Publish Python package
const wheelFile = fs.readFileSync('dist/my_package-1.0.0-py3-none-any.whl');
await api.PyPI.publishPackage(123, {
  content: wheelFile,
  filename: 'my_package-1.0.0-py3-none-any.whl'
});

Configure pip/twine:

# .pypirc
[distutils]
index-servers = gitlab

[gitlab]
repository = https://gitlab.com/api/v4/projects/123/packages/pypi
username = __token__
password = ${GITLAB_TOKEN}

NuGet Registry

Publish and manage NuGet packages.

/**
 * NuGet resource class for NuGet package operations
 */
class NuGet<C extends boolean = false> {
  /**
   * Publish a NuGet package
   * @param projectId - Project ID
   * @param file - NuGet package file (.nupkg)
   * @returns Published package info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    file: Blob | Buffer,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

import * as fs from 'fs';

// Publish NuGet package
const nupkgFile = fs.readFileSync('MyPackage.1.0.0.nupkg');
await api.NuGet.publishPackage(123, nupkgFile);

Configure NuGet:

# Add source
dotnet nuget add source "https://gitlab.com/api/v4/projects/123/packages/nuget/index.json" \
  --name gitlab --username any --password ${GITLAB_TOKEN}

Composer Registry

Publish and manage PHP Composer packages.

/**
 * Composer resource class for PHP Composer operations
 */
class Composer<C extends boolean = false> {
  /**
   * Publish a Composer package
   * @param projectId - Project ID
   * @param file - Package archive (zip or tar.gz)
   * @returns Published package info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    file: Blob | Buffer,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Configure Composer:

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://gitlab.com/api/v4/group/123/-/packages/composer/packages.json"
    }
  ],
  "config": {
    "gitlab-token": {
      "gitlab.com": "your-token"
    }
  }
}

Conan Registry

Publish and manage Conan C++ packages.

/**
 * Conan resource class for Conan package operations
 */
class Conan<C extends boolean = false> {
  /**
   * Publish a Conan package
   * @param projectId - Project ID
   * @param packageName - Package name
   * @param packageVersion - Package version
   * @param file - Package file
   * @returns Published package info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    packageName: string,
    packageVersion: string,
    file: Blob | Buffer,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Configure Conan:

# Add remote
conan remote add gitlab https://gitlab.com/api/v4/projects/123/packages/conan

# Authenticate
conan user -p ${GITLAB_TOKEN} -r gitlab any

Helm Registry

Publish and manage Helm charts.

/**
 * Helm resource class for Helm chart operations
 */
class Helm<C extends boolean = false> {
  /**
   * Publish a Helm chart
   * @param projectId - Project ID
   * @param file - Chart package (.tgz file)
   * @returns Published chart info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    file: { content: Blob | Buffer; filename: string },
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

import * as fs from 'fs';

// Publish Helm chart
const chartFile = fs.readFileSync('my-chart-1.0.0.tgz');
await api.Helm.publishPackage(123, {
  content: chartFile,
  filename: 'my-chart-1.0.0.tgz'
});

Configure Helm:

# Add repository
helm repo add --username any --password ${GITLAB_TOKEN} \
  gitlab https://gitlab.com/api/v4/projects/123/packages/helm/stable

Go Proxy

Manage Go modules.

/**
 * GoProxy resource class for Go module operations
 */
class GoProxy<C extends boolean = false> {
  // Go packages are published via git tags
  // This resource provides proxy functionality for fetching
}

Configure Go:

# Set GOPROXY environment variable
export GOPROXY=https://gitlab.com/api/v4/projects/123/packages/go,direct

# Or in go.env
GOPROXY=https://gitlab.com/api/v4/projects/123/packages/go,direct
GOPRIVATE=gitlab.com/mygroup/*

RubyGems Registry

Publish and manage Ruby gems.

/**
 * RubyGems resource class for gem operations
 */
class RubyGems<C extends boolean = false> {
  /**
   * Publish a Ruby gem
   * @param projectId - Project ID
   * @param file - Gem file (.gem)
   * @returns Published gem info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    file: Blob | Buffer,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Configure RubyGems:

# Add to ~/.gem/credentials
---
https://gitlab.com/api/v4/projects/123/packages/rubygems: ${GITLAB_TOKEN}

Debian Registry

Publish and manage Debian packages.

/**
 * Debian resource class for Debian package operations
 */
class Debian<C extends boolean = false> {
  /**
   * Publish a Debian package
   * @param projectId - Project ID
   * @param file - Debian package file (.deb)
   * @param distribution - Distribution name (e.g., 'bullseye')
   * @returns Published package info
   */
  publishPackage<E extends boolean = false>(
    projectId: string | number,
    file: { content: Blob | Buffer; filename: string },
    distribution: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Configure APT:

# Add to /etc/apt/sources.list.d/gitlab.list
deb [trusted=yes] https://any:${GITLAB_TOKEN}@gitlab.com/api/v4/projects/123/packages/debian bullseye main

Package Registry Operations

Additional package registry operations.

/**
 * PackageRegistry resource class
 */
class PackageRegistry<C extends boolean = false> {
  /**
   * List all packages (project or group level)
   */
  allPackages<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    resourceId: string | number,
    options?: {
      resourceType: 'project' | 'group';
      packageType?: string;
      packageName?: string;
    } & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<PackageSchema[], C, E, P>>;
}

Package Registry Authentication

All package registries support multiple authentication methods:

Personal Access Token

# Most registries accept token in URL or headers
curl --header "PRIVATE-TOKEN: your-token" \
  https://gitlab.com/api/v4/projects/123/packages/...

Deploy Token

# Project Settings > Repository > Deploy Tokens
username=gitlab+deploy-token-{id}
password={token}

CI Job Token

# .gitlab-ci.yml
publish:
  script:
    - # Use $CI_JOB_TOKEN for authentication
    - curl --header "JOB-TOKEN: $CI_JOB_TOKEN" ...

Related Package Resources

Additional package-related operations:

ProjectPackages - Project-specific package operations
GroupPackages - Group-level package management

See Additional Resources for detailed documentation.

Install with Tessl CLI

npx tessl i tessl/npm-gitbeaker--rest

docs

additional-resources.md

cicd.md

client-configuration.md

package-registries.md

projects.md

repository-management.md

users.md

tile.json

tessl/npm-gitbeaker--rest