@microature/gitlab-publisher

A CLI tool for easily publishing npm packages to GitLab Package Registry.

Features

• 🚀 Publish npm packages to GitLab Package Registry with ease
• 🔄 Automatic project detection using glab CLI or git remote
• 📦 Support for both project-level and group-level registries
• 🏷️ Version management (latest, dev, beta tags)
• 🔒 Secure token management via environment variables
• 🎨 Beautiful CLI output with colors and spinners
• 🧪 Dry-run mode for testing

Installation

# Install globally
npm install -g @microature/gitlab-publisher

# Or use as a dev dependency
npm install -D @microature/gitlab-publisher

Prerequisites

1. GitLab Personal Access Token with api and write_registry scopes
2. Your package.json should have a prepublishOnly script for building (if needed)
3. (Optional) glab CLI for automatic project detection

Quick Start

1. Create a .env file in your project root:

GITLAB_AUTH_TOKEN=your-personal-access-token
# Optional: Will be auto-detected if not provided
GITLAB_PROJECT_ID=your-project-id

2. Add to your package.json (optional):

{
  "scripts": {
    "prepublishOnly": "npm run build",
    "publish:gitlab": "gitlab-publish",
    "publish:dev": "gitlab-publish dev",
    "publish:beta": "gitlab-publish beta --bump minor"
  }
}

3. Publish your package:

# Publish latest version
gitlab-publish

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

# Publish development version
gitlab-publish dev

# Publish beta version
gitlab-publish beta --bump minor

# Dry run (test without publishing)
gitlab-publish --dry-run

Usage

gitlab-publish [type] [options]

Arguments

• type - Publish type: latest (default), dev, beta

Options

• --bump <type> - Version bump type: patch, minor, major
• --dry-run - Run without actually publishing
• --registry-type <type> - Registry type: project (default), group
• --token <token> - GitLab Personal Access Token (overrides .env)
• --project-id <id> - GitLab Project ID (auto-detected if not provided)
• --no-build - Skip prepublishOnly script
• --verbose - Show detailed output
• -V, --version - Output the version number
• -h, --help - Display help for command

Examples

Basic Publishing

# Publish current version
gitlab-publish

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

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

Group-Level Registry

# Use group-level registry instead of project-level
gitlab-publish --registry-type group

Configuration

Environment Variables

• GITLAB_AUTH_TOKEN - Your GitLab Personal Access Token (required)
• GITLAB_PROJECT_ID - Project ID (optional, auto-detected)

Package.json Requirements

Your package must have:

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

Example:

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

How It Works

1. Auto-detection: Automatically detects project information from git remote or glab CLI
2. Configuration: Creates a temporary .npmrc with GitLab registry settings
3. Publishing: Runs npm publish with appropriate settings
4. Cleanup: Removes temporary .npmrc file for security

Troubleshooting

Authentication Error (403 Forbidden)

Ensure your Personal Access Token has the correct scopes:

• api
• write_registry
• read_registry (optional but recommended)

Project ID Not Found

The tool tries to auto-detect the project ID using:

1. glab CLI (if installed)
2. Git remote URL
3. GitLab API

If auto-detection fails, set GITLAB_PROJECT_ID in your .env file.

No prepublishOnly Script

Add a prepublishOnly script to your package.json:

{
  "scripts": {
    "prepublishOnly": "npm run build"
  }
}

Or use --no-build flag to skip the build step.

License

MIT

Contributing

Issues and pull requests are welcome at GitLab.

Author

microature