Publish to Registry

Learn how to publish your template to a CyanPrint registry for others to discover and use.

Overview

Publishing a template involves:

Creating an account on a CyanPrint registry
Generating an API token
Building and pushing Docker images
Registering the template with CyanPrint

You can use the official cyanprint.dev registry or host your own. This guide covers both options.

Prerequisites

A completed template ready to publish
Docker with buildx support
CyanPrint CLI installed

Create an Account

Navigate to cyanprint.dev
Click Sign Up or Register
Complete the registration process
Verify your email address

If your organization hosts a private CyanPrint registry:

Contact your administrator for access
Get the registry URL (e.g., registry.internal.example.com)
Obtain credentials for authentication

Self-hosted registries require additional setup. See your organization's documentation for specific instructions.

Generate an API Token

Log in to cyanprint.dev
Navigate to Settings > API Tokens
Click Generate New Token
Give it a descriptive name (e.g., "CI/CD Publishing")
Select appropriate scopes (minimum: template:push)
Click Generate
Copy the token immediately - it won't be shown again

# Store the token securely
export CYAN_TOKEN="your-token-here"

Follow your organization's token generation process. Typically:

Log in to your registry's web interface
Navigate to API settings or profile settings
Generate a token with push permissions
Store it securely

# Store the token securely
export CYAN_TOKEN="your-token-here"

# If using a custom registry URL
export CYAN_REGISTRY="https://registry.internal.example.com"

Never commit API tokens to version control. Use environment variables or secret management tools.

Authenticate the CLI

Verify your CLI can authenticate with the registry:

# Test authentication
cyanprint auth status

# Or manually login
cyanprint login --token $CYAN_TOKEN

For self-hosted registries:

# Specify custom registry
cyanprint login --token $CYAN_TOKEN --registry $CYAN_REGISTRY

Build Docker Images

Build both the template and blob images:

# Build template image
docker buildx build --platform linux/amd64,linux/arm64 \
  -f cyan/template.Dockerfile \
  -t myorg/my-template:1.0.0 \
  --push .

# Build blob image
docker buildx build --platform linux/amd64,linux/arm64 \
  -f cyan/blob.Dockerfile \
  -t myorg/my-template-blob:1.0.0 \
  --push .

Replace myorg/my-template with your actual image name. Use Docker Hub, GHCR, or your private registry.

For GitHub Container Registry:

# Login to GHCR first
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Build and push
docker buildx build --platform linux/amd64,linux/arm64 \
  -f cyan/template.Dockerfile \
  -t ghcr.io/myorg/my-template:1.0.0 \
  --push .

Publish to Registry

cyanprint push template --token $CYAN_TOKEN \
  myorg/my-template-blob 1.0.0 \
  myorg/my-template 1.0.0

This command:

Registers the template metadata
Links the blob and template images
Makes the template discoverable

Verify Publication

Confirm your template is available:

# List your templates
cyanprint list myorg/

# Get template details
cyanprint info myorg/my-template:1.0.0

CI/CD Integration

Automate template publishing with GitHub Actions.

GitHub Actions Workflow

Create .github/workflows/publish.yml:

.github/workflows/publish.yml

name: Publish Template

on:
  release:
    types: [published]

permissions:
  contents: read
  packages: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT

      - name: Build and Push Template
        run: |
          docker buildx build --platform linux/amd64,linux/arm64 \
            -f cyan/template.Dockerfile \
            -t ghcr.io/${{ github.repository_owner }}/my-template:${{ steps.version.outputs.VERSION }} \
            --push .

      - name: Build and Push Blob
        run: |
          docker buildx build --platform linux/amd64,linux/arm64 \
            -f cyan/blob.Dockerfile \
            -t ghcr.io/${{ github.repository_owner }}/my-template-blob:${{ steps.version.outputs.VERSION }} \
            --push .

      - name: Register with CyanPrint
        run: |
          cyanprint push template --token ${{ secrets.CYAN_TOKEN }} \
            ghcr.io/${{ github.repository_owner }}/my-template-blob ${{ steps.version.outputs.VERSION }} \
            ghcr.io/${{ github.repository_owner }}/my-template ${{ steps.version.outputs.VERSION }}

Store your CYAN_TOKEN as a GitHub secret. Go to Settings > Secrets and variables > Actions > New repository secret.

Triggering the Workflow

Create a new release in GitHub
Tag it with a semantic version (e.g., v1.0.0)
The workflow automatically builds and publishes

Best Practices

Versioning

Use semantic versioning (MAJOR.MINOR.PATCH)
Tag both specific versions and latest
Document breaking changes in release notes

# Build with multiple tags
docker buildx build \
  -t myorg/my-template:1.0.0 \
  -t myorg/my-template:1.0 \
  -t myorg/my-template:latest \
  --push .

Security

Use scoped tokens with minimum required permissions
Rotate tokens regularly
Never expose tokens in logs or error messages
Use GitHub secrets or similar for CI/CD

Testing Before Publishing

Always test locally before publishing:

# Build locally without push
docker buildx build --platform linux/amd64 \
  -f cyan/template.Dockerfile \
  -t myorg/my-template:test \
  --load .

# Test the template
cyanprint create myorg/my-template:test ./test-output

Troubleshooting

Authentication Failed

# Verify token is set
echo $CYAN_TOKEN

# Check token validity
cyanprint auth status

Image Not Found

# Verify images exist
docker images | grep my-template

# Check registry connectivity
docker pull myorg/my-template:1.0.0

Registry Unavailable

Check registry status at status.cyanprint.dev
Try again after a few minutes
Contact support if the issue persists

Next Steps

Registry Architecture

Understand how Docker and CyanPrint registries work together

Dockerfiles Reference

Learn more about template and blob Dockerfiles

Automated Testing

Set up automated testing for your templates

Publish to Registry

Registry Architecture

Dockerfiles Reference

Automated Testing

On this page