@glpkg/publisher

A CLI tool for publishing NPM packages to GitLab Package Registry.

Installation

# Install globally
npm install -g @glpkg/publisher

# Or as a dev dependency
npm install -D @glpkg/publisher

Features

• Automatic project detection using glab CLI or git remote
• Support for project-level and group-level registries
• Version management (latest, dev, beta tags)
• Secure token management via @glpkg/config
• Dry-run mode for testing
• Git tag and push support

Quick Start

1. Configure your token

gitlab-config save YOUR_GITLAB_TOKEN

2. Publish

# Publish current version
gitlab-publish

# Publish with version bump
gitlab-publish --bump patch

That's it! The publisher auto-detects your project and handles everything.

Usage

gitlab-publish [type] [options]

Arguments

Argument	Description	Default
type	Publish type: latest, dev, beta	latest

Options

Option	Description
--bump <type>	Version bump: patch, minor, major
--dry-run	Run without actually publishing
--token <token>	GitLab token (overrides saved token)
--no-build	Skip prepublishOnly script
--git-tag <bool>	Create git commit and tag (default: true)
--push <bool>	Push commits and tags to remote (default: true)
--force	Skip git clean check, delete existing version if present
--verbose	Show detailed output

Examples

Basic Publishing

# Publish current version
gitlab-publish

# Publish with patch version bump (1.0.0 -> 1.0.1)
gitlab-publish --bump patch

# Publish with minor version bump (1.0.0 -> 1.1.0)
gitlab-publish --bump minor

Development Versions

# Publish dev version with git commit hash
# Example: 1.0.0 -> 1.0.1-dev.abc1234
gitlab-publish dev

Beta Versions

# Publish beta version
gitlab-publish beta

# Publish beta with minor bump (1.0.0 -> 1.1.0-beta.0)
gitlab-publish beta --bump minor

Testing

# Test configuration without publishing
gitlab-publish --dry-run

# Verbose output for debugging
gitlab-publish --verbose --dry-run

Token Configuration

The publisher looks for a token in this order:

1. --token command-line option
2. Saved token via gitlab-config save ← Recommended
3. GITLAB_AUTH_TOKEN environment variable

Required Token Scopes

• api - Full API access
• write_registry - Write package registry
• read_registry - Read package registry (recommended)

Package.json Requirements

Your package should have:

• A scoped name (e.g., @yourscope/package-name)
• A prepublishOnly script (if building is required)

{
  "name": "@yourscope/your-package",
  "version": "1.0.0",
  "scripts": {
    "build": "your-build-command",
    "prepublishOnly": "npm run build"
  }
}

How It Works

1. Auto-detection: Detects project info from git remote or glab CLI
2. Configuration: Creates temporary .npmrc with GitLab registry settings
3. Build: Runs prepublishOnly script (if exists)
4. Publishing: Runs npm publish with appropriate settings
5. Git: Creates commit, tag, and pushes (by default)
6. Cleanup: Removes temporary .npmrc for security

Troubleshooting

403 Forbidden

Ensure your token has the correct scopes:

• api
• write_registry
• read_registry

Project ID Not Found

Make sure:

1. You have run gitlab-config save YOUR_TOKEN
2. You are in a Git repository with GitLab remote
3. The repository exists on GitLab

Git Not Clean

The publisher requires a clean git working directory by default. Either:

• Commit your changes first
• Use --force to skip the check (not recommended)