Publishing Guide¶

This guide explains how to publish SPOT Contracts SDKs to GitLab package registries.

Configuration¶

Environment Setup¶

Copy the example file:
```
cp .env.example .env
```

Edit .env with your settings:

# GitLab Instance URL


# GitLab Project ID (found in Settings > General)
CI_PROJECT_ID=303

# GitLab Personal Access Token (with 'api' scope)
GITLAB_TOKEN=glpat-YOUR_TOKEN_HERE

# Path to CA certificate (for self-signed GitLab)
GITLAB_CA_CERT=certs/gitlab-ca.crt

Add your CA certificate (if using self-signed GitLab):
Save certificate as certs/gitlab-ca.crt
This file is gitignored for security

CI/CD Publishing¶

The GitLab CI/CD pipeline automatically publishes SDKs when you create version tags.

Python SDK¶

# Tag format: python-v<version>
git tag python-v1.0.0
git push origin python-v1.0.0

TypeScript SDK¶

# Tag format: typescript-v<version>
git tag typescript-v1.0.0
git push origin typescript-v1.0.0

CI/CD Process¶

The CI/CD pipeline will:

Validate - Check OpenAPI specifications
Test - Run comprehensive contract tests
Build - Generate SDK package
Authenticate - Configure registry using CI_JOB_TOKEN
Publish - Upload to GitLab package registry

Local Publishing¶

With the .env file configured, you can publish directly from your machine.

Version Management¶

# Check current versions and registry status
make check-versions

# Bump version before publishing
make bump-python VERSION=1.0.2
make bump-typescript VERSION=1.0.1

Build Packages Locally¶

# Build Python SDK package
make publish-python-local

# Build TypeScript SDK package
make publish-typescript-local

This creates packages in:

Python: sdk/python/dist/
TypeScript: sdk/typescript/dist/

Publish to Registry¶

# Publish Python SDK
make publish-python

# Publish TypeScript SDK
make publish-typescript

Handling Version Conflicts¶

If you get a "file name has already been taken" error:

Check existing versions: make check-versions
Bump to a new version: make bump-python VERSION=1.0.2
Publish again: make publish-python

Implementation Details¶

Python SDK Publishing¶

Build Process: 1. Poetry builds wheel and sdist packages 2. Packages are created in sdk/python/dist/

Publishing Process:

# Configure GitLab PyPI repository
poetry config repositories.gitlab https://upload.pypi.org/legacy/

# Configure authentication
poetry config http-basic.gitlab gitlab-ci-token ${CI_JOB_TOKEN}

# Publish to registry
poetry publish --repository gitlab

Registry URL:

https://upload.pypi.org/legacy/

TypeScript SDK Publishing¶

Build Process: 1. TypeScript compiles to JavaScript 2. Package is created with npm

Publishing Process:

# Create .npmrc with registry and auth
echo '@spot:registry=https://registry.npmjs.org/' > .npmrc
echo '//registry.npmjs.org/:_authToken=${CI_JOB_TOKEN}' >> .npmrc

# Publish to registry
npm publish

Registry URL:

https://registry.npmjs.org/

Package Registries¶

Python (PyPI)¶

Registry:

https://upload.pypi.org/legacy/

Package Name:

spot-sdk

Installation:

pip install spot-sdk \
  --index-url https://pypi.org/simple/

TypeScript (NPM)¶

Registry:

https://registry.npmjs.org/

Package Name:

@spot/contracts

Installation:

# Configure registry
npm config set @spot:registry https://registry.npmjs.org/

# Install package
npm install @spot/contracts

Version Management¶

Independent Versioning¶

Python and TypeScript SDKs have independent version numbers
Each can have different major, minor, and patch versions
Use semantic versioning (MAJOR.MINOR.PATCH)

Version Files¶

Python SDK: Version in sdk/python/pyproject.toml
TypeScript SDK: Version in sdk/typescript/package.json

Checking Versions¶

# Check current SDK versions
make check-versions

# Output shows:
# Python SDK: 1.0.0
# TypeScript SDK: 2.1.0
# Latest published versions from registries

Bumping Versions¶

# Bump Python SDK version
make bump-python VERSION=1.0.2

# Bump TypeScript SDK version
make bump-typescript VERSION=2.1.1

Publishing Workflow¶

Complete Publishing Process¶

Update OpenAPI specs in openapi/ directory
Validate changes: make validate
Generate SDKs: make generate
Run tests: make test
Commit changes: git add . && git commit -m "Update contracts"
Bump version: make bump-python VERSION=1.1.0
Create tag: git tag python-v1.1.0
Push changes: git push origin main
Push tag: git push origin python-v1.1.0
Monitor CI/CD: Watch GitLab pipeline for automatic publishing

Pre-Publishing Checklist¶

[ ] All OpenAPI specs are valid (make validate)
[ ] All tests pass (make test)
[ ] Coverage is 95%+ (make test)
[ ] Documentation is updated (make docs)
[ ] CHANGELOG.md is updated
[ ] Version number follows semantic versioning
[ ] No uncommitted changes

Troubleshooting¶

Authentication Errors¶

Problem: Publishing fails with authentication error

Solution:

Ensure CI_PROJECT_ID and GITLAB_TOKEN are set correctly in .env
Verify token has appropriate scopes (api, write_repository)
Check project ID matches your GitLab project: Settings → General → Project ID

# Test GitLab token
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "$GITLAB_URL/api/v4/user"

Package Already Exists¶

Problem: Error "file name has already been taken"

Solution:

Each version can only be published once
Increment version number in pyproject.toml or package.json
Use unique version tags for each release

# Check what versions exist
make check-versions

# Bump to new version
make bump-python VERSION=1.0.3

Docker Issues¶

Problem: Publishing fails with Docker errors

Solution:

Ensure Docker is running: docker compose build
Check container has network access for publishing
Rebuild containers: make build

# Check Docker status
docker compose ps

# View container logs
docker compose logs dev

Version Mismatch¶

Problem: Tag version doesn't match package version

Solution:

Ensure tag format matches: python-v1.0.0 or typescript-v1.0.0
Version in tag should match version in package file
Use make bump-* commands to keep versions in sync

# Correct tag format
git tag python-v1.0.0   # Matches version 1.0.0 in pyproject.toml
git tag typescript-v2.1.0  # Matches version 2.1.0 in package.json

Security Notes¶

Token Management¶

Never commit tokens to the repository
Use .env file (gitignored) for local development
Use CI/CD variables for production deployments
Rotate personal access tokens regularly
Use minimal token scopes (only what's needed)

CA Certificates¶

Self-signed certificates go in certs/ directory
certs/ directory is gitignored
Never commit certificates to repository
Each developer needs their own certificate copy

Support¶

Issues: GitLab Issues
Documentation: Main Documentation
CI/CD Logs: Check GitLab CI/CD pipeline logs for detailed errors