npm package: @microature/gitlab-publisher
Description: CLI tool for publishing npm packages to GitLab Package Registry
Author: microature
Latest version: 0.2.0

# @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

```bash
# 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:

```env
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):

```json
{
  "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:

```bash
# 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

```bash
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

```bash
# Publish current version
gitlab-publish

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

### Development Versions

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

### Beta Versions

```bash
# 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

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

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

### Group-Level Registry

```bash
# 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:
```json
{
  "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:
```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](https://gitlab.com/microature/gitlab-publisher).

## Author

microature