# Publishing

Publish packages to GPM registries with enterprise-grade security and access control.

## Overview

GPM provides comprehensive publishing commands for creating, packaging, and publishing packages to registries. The system supports multiple access levels and distribution channels for professional game development workflows.

## Commands

| Command                                                     | Description                 | Usage                        |
| ----------------------------------------------------------- | --------------------------- | ---------------------------- |
| [`gpm publish`](/cli-reference/cli/publishing/publish.md)   | Publish package to registry | `gpm publish [package-spec]` |
| [`gpm pack`](/cli-reference/cli/publishing/pack.md)         | Create package tarball      | `gpm pack [package-spec...]` |
| [`gpm dist-tag`](/cli-reference/cli/publishing/dist-tag.md) | Manage distribution tags    | `gpm dist-tag [command]`     |

## Quick Start

### Basic Publishing

```bash
# Publish current directory
gpm publish

# Publish specific package
gpm publish ./my-package

# Publish with access level
gpm publish --access=scoped
```

### Package Preparation

```bash
# Initialize package
gpm init

# Pack package
gpm pack

# Publish package
gpm publish --access=scoped
```

### Distribution Management

```bash
# Add distribution tags
gpm dist-tag add com.company.package beta 1.0.0-beta.1
gpm dist-tag add com.company.package stable 1.0.0

# List distribution tags
gpm dist-tag list com.company.package
```

## Access Levels

### Public Packages

* **Visibility**: Available globally without authentication
* **Publishing**: Requires authentication
* **Registry**: Global registry (`https://registry.gpm.sh`)
* **Use Case**: Open source packages, industry standards

### Scoped Packages

* **Visibility**: Available on tenant registry without authentication
* **Publishing**: Requires authentication
* **Registry**: Tenant registry (`https://<tenant>.gpm.sh`)
* **Use Case**: Studio-specific packages, internal tools

### Private Packages

* **Visibility**: Available on tenant registry with authentication
* **Publishing**: Requires authentication
* **Registry**: Tenant registry (`https://<tenant>.gpm.sh`)
* **Use Case**: Proprietary packages, sensitive content

## Publishing Workflow

### 1. Package Preparation

```bash
# Initialize new package
gpm init

# Edit package.json
# Add source code
# Add documentation

# Validate package
gpm pack --dry-run
```

### 2. Package Creation

```bash
# Create tarball
gpm pack

# Verify tarball
gpm pack package.tgz --dry-run
```

### 3. Publishing

```bash
# Publish to registry
gpm publish --access=scoped

# Add distribution tags
gpm dist-tag add com.company.package latest 1.0.0
```

### 4. Verification

```bash
# Check package info
gpm info com.company.package

# Search for package
gpm search com.company.package
```

## Package Structure

### Required Files

* **package.json**: Package metadata and configuration
* **README.md**: Package documentation (recommended)
* **LICENSE**: Package license (recommended)

### Package.json Requirements

```json
{
  "name": "com.company.package",
  "version": "1.0.0",
  "description": "Package description",
  "author": "Author Name",
  "license": "MIT",
  "unity": "2021.3",
  "keywords": ["unity", "package"]
}
```

### File Inclusion

GPM includes files based on:

* **package.json**: Files specified in `files` field
* **.npmignore**: Files to exclude (if present)
* **.gitignore**: Git ignored files (if no .npmignore)
* **Default patterns**: Common package files

## Distribution Tags

### Common Tags

* **latest**: Default tag for most recent stable version
* **beta**: Beta release channel
* **alpha**: Alpha release channel
* **stable**: Stable release channel
* **next**: Next major version preview

### Tag Management

```bash
# Add tags
gpm dist-tag add com.company.package beta 1.0.0-beta.1
gpm dist-tag add com.company.package stable 1.0.0

# List tags
gpm dist-tag list com.company.package

# Remove tags
gpm dist-tag remove com.company.package beta
```

## Registry Configuration

### Global Registry

```bash
# Use global registry
gpm config set registry https://registry.gpm.sh

# Publish to global registry
gpm publish --access=public
```

### Tenant Registry

```bash
# Use tenant registry
gpm config set registry https://company.gpm.sh

# Publish to tenant registry
gpm publish --access=scoped
```

### Registry Override

```bash
# Override registry for single command
gpm publish --registry https://custom.gpm.sh --access=scoped
```

## Authentication

### Login Required

Publishing requires authentication:

```bash
# Login to registry
gpm login

# Check authentication status
gpm whoami

# Publish package
gpm publish --access=scoped
```

### Registry-Specific Authentication

```bash
# Login to global registry
gpm login --registry https://registry.gpm.sh

# Login to tenant registry
gpm login --registry https://company.gpm.sh
```

## Best Practices

### Package Development

```bash
# Use semantic versioning
gpm version patch  # 1.0.0 → 1.0.1
gpm version minor  # 1.0.0 → 1.1.0
gpm version major  # 1.0.0 → 2.0.0

# Test before publishing
gpm pack --dry-run
gpm publish --dry-run
```

### Release Management

```bash
# Create release branches
git checkout -b release/1.0.0

# Publish beta version
gpm publish --tag=beta
gpm dist-tag add com.company.package beta 1.0.0-beta.1

# Publish stable version
gpm publish --tag=latest
gpm dist-tag add com.company.package stable 1.0.0
```

### Security

```bash
# Use appropriate access levels
gpm publish --access=public    # Open source
gpm publish --access=scoped    # Studio packages
gpm publish --access=private   # Proprietary packages

# Authenticate securely
gpm login
gpm whoami
```

## Error Handling

### Common Errors

* **Package validation failed**: Check package.json format
* **Authentication required**: Run `gpm login`
* **Access level mismatch**: Verify registry and access level
* **Package already exists**: Update version or use different name

### Troubleshooting

1. **Validation errors**: Check package.json and file structure
2. **Authentication issues**: Verify login status with `gpm whoami`
3. **Registry errors**: Check registry URL and network connectivity
4. **Access errors**: Verify access level matches registry type

## CI/CD Integration

### Automated Publishing

```bash
# Publish in CI
gpm login
gpm publish --access=scoped

# Add tags in CI
gpm dist-tag add com.company.package ci-build $BUILD_NUMBER
```

### Environment Variables

```bash
# Use environment variables
export GPM_REGISTRY=https://company.gpm.sh
export GPM_ACCESS=scoped

# Publish with environment variables
gpm publish
```

## Related Commands

* [Package Management](/cli-reference/cli/package-management.md) - Package installation and management
* [Registry Operations](/cli-reference/cli/registry.md) - Package search and information
* [Authentication](/cli-reference/cli/authentication.md) - User authentication

## See Also

* [Package Guidelines](https://github.com/gpm-sh/docs/blob/main/packages/README.md) - Package naming and structure
* [Access Levels](/package-guidelines/packages/access-levels.md) - Package visibility controls
* [Registry Resolution](https://github.com/gpm-sh/docs/blob/main/packages/registry-resolution.md) - Registry configuration


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gpm.sh/cli-reference/cli/publishing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.