code-server/PUBLISHING.md

Publishing Guide

This document explains how to set up and use automatic publishing for code-server.

Overview

The project includes automatic publishing workflows that handle:

• Building and testing the project
• Publishing to npm
• Creating GitHub releases
• Building and pushing Docker images

Setup

1. Required Secrets

Configure the following secrets in your GitHub repository:

NPM Publishing

• NPM_TOKEN: Your npm authentication token
  • Get it from: https://www.npmjs.com/settings/tokens
  • Needs "Automation" access for publishing

Docker Publishing

• DOCKER_USERNAME: Your Docker Hub username
• DOCKER_PASSWORD: Your Docker Hub password or access token

2. GitHub Actions Permissions

Ensure the following permissions are enabled in your repository:

• Contents: write (for creating releases)
• Packages: write (for publishing packages)
• Actions: read (for workflow execution)

Usage

Automatic Publishing

Publishing happens automatically when you push a version tag:

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

The workflow will automatically:

1. Build and test the project
2. Publish to npm
3. Create a GitHub release
4. Build and push Docker images

Manual Publishing

You can also trigger publishing manually:

1. Go to the "Actions" tab in your GitHub repository
2. Select "Auto Publish" workflow
3. Click "Run workflow"
4. Enter the version (e.g., v1.0.0)
5. Click "Run workflow"

Using the Release Script

For convenience, use the included release script:

# Dry run to see what would happen
./scripts/release.sh v1.0.0 --dry-run

# Create a release
./scripts/release.sh v1.0.0

# Skip tests (if you're confident)
./scripts/release.sh v1.0.0 --skip-tests

# Skip build (if already built)
./scripts/release.sh v1.0.0 --skip-build

Workflow Details

Build and Test Job

• Runs on Ubuntu latest
• Installs dependencies (skipping VS Code submodule deps to avoid kerberos issues)
• Builds the project
• Runs unit tests
• Creates release package
• Uploads build artifacts

NPM Publishing Job

• Downloads build artifacts
• Publishes to npm registry
• Uses the version from the tag

GitHub Release Job

• Creates a GitHub release
• Includes release notes
• Attaches the release package
• Marks as prerelease for beta/alpha versions

Docker Publishing Job

• Builds multi-architecture Docker images (linux/amd64, linux/arm64)
• Pushes to both Docker Hub and GitHub Container Registry
• Tags with version and latest

Version Format

Versions should follow semantic versioning:

• v1.0.0 - Stable release
• v1.0.0-beta - Beta release
• v1.0.0-alpha - Alpha release
• v1.0.0-rc1 - Release candidate

Troubleshooting

Build Failures

• Check that all dependencies are properly installed
• Ensure the kerberos issue is resolved (VS Code submodule deps are skipped)
• Verify Node.js version compatibility

NPM Publishing Failures

• Verify NPM_TOKEN is correctly set
• Check that the version doesn't already exist on npm
• Ensure the package name is available

Docker Publishing Failures

• Verify Docker credentials are correct
• Check that the Dockerfile builds successfully
• Ensure multi-architecture builds are supported

GitHub Release Failures

• Verify GITHUB_TOKEN has sufficient permissions
• Check that the tag doesn't already exist
• Ensure the release package was created successfully

Monitoring

Monitor the publishing process:

1. Go to the "Actions" tab in your GitHub repository
2. Look for the "Auto Publish" workflow
3. Check individual job logs for detailed information

Rollback

If a release needs to be rolled back:

1. Unpublish the npm package (if within 72 hours)
2. Delete the GitHub release
3. Delete the Docker images
4. Delete the git tag

# Delete local and remote tag
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0