mirror of
https://github.com/cdr/code-server.git
synced 2025-12-13 20:03:39 +01:00
5d4c8d26c7
- Add comprehensive auto-publish GitHub Actions workflow - Fix kerberos build issues by skipping VS Code submodule deps - Add Dockerfile for containerized builds - Add release script for easy version management - Add comprehensive publishing documentation - Update build workflow to use SKIP_SUBMODULE_DEPS=1
156 lines
3.8 KiB
Markdown
156 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Delete local and remote tag
|
|
git tag -d v1.0.0
|
|
git push origin :refs/tags/v1.0.0
|
|
```
|