Pixi Repositories

This section provides comprehensive documentation for using CloudRepo with Pixi, the modern cross-platform package and environment management tool.

Introduction to Pixi

What is Pixi?

Pixi is a revolutionary cross-platform package management tool that bridges the conda and PyPI ecosystems, offering developers a unified solution for managing dependencies, environments, and workflows across Windows, macOS, and Linux. Built in Rust for exceptional performance, Pixi represents a significant evolution in Python package management.

Key advantages of Pixi include:

Cross-platform by design: Single configuration works seamlessly across Windows, macOS, and Linux
Dual ecosystem support: Native integration with both conda-forge and PyPI packages
Blazing fast performance: Up to 10x faster than conda, 4x faster than micromamba
Deterministic environments: Lock files ensure reproducible builds across all platforms
Language agnostic: Manage Python, R, C++, Rust, and other language dependencies
Built-in task runner: Define and execute project tasks without additional tools
Modern configuration: Single pixi.toml file replaces multiple config files

Why Use Pixi with CloudRepo?

Combining Pixi’s modern workflow with CloudRepo’s private repository hosting provides:

Private package distribution: Securely share internal packages across your organization
Cross-platform consistency: Ensure teams on different OS platforms get identical environments
Cost efficiency: Save up to 90% compared to enterprise alternatives like JFrog Artifactory
No egress fees: Download packages without worrying about bandwidth charges
Simplified CI/CD: One configuration file works across all build environments
Mixed dependencies: Seamlessly combine public PyPI/conda packages with private CloudRepo packages

Prerequisites

Before configuring Pixi to work with CloudRepo, ensure you have:

CloudRepo Account and Repository
- An active CloudRepo organization account
- A Python repository created in the CloudRepo Admin Portal
- A repository user with appropriate permissions (upload/download)
Note

Your admin user cannot directly access repositories for security reasons. Always create a dedicated repository user in the CloudRepo Admin Portal.

If you haven’t completed these steps, please refer to:
- Creating a Repository
- Creating Users

Pixi Installation

Install Pixi using the official installer:

Installing Pixi (Recommended Method)

# macOS and Linux
curl -fsSL https://pixi.sh/install.sh | bash

# Windows (PowerShell)
iwr -useb https://pixi.sh/install.ps1 | iex

Or install via conda/mamba:

Installing Pixi via Conda

conda install -c conda-forge pixi
# or
mamba install -c conda-forge pixi

Python Environment
- Python 3.8 or higher (managed by Pixi)
- A project directory for your Pixi configuration

Configuration

Basic Pixi Configuration for CloudRepo

Initialize a new Pixi project or add CloudRepo to an existing project:

Initializing a Pixi Project

# Create new project
pixi init my-project
cd my-project

# Or initialize in existing directory
pixi init

This creates a pixi.toml file. Configure it to use CloudRepo as a PyPI index:

pixi.toml - Basic CloudRepo Configuration

[project]
name = "my-project"
version = "0.1.0"
description = "Project using CloudRepo for private packages"
authors = ["Your Team <team@example.com>"]
channels = ["conda-forge"]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

[dependencies]
python = ">=3.8,<3.12"

[pypi-dependencies]
# Public packages from PyPI
requests = ">=2.28.0"
pandas = "*"

# Private packages from CloudRepo
my-private-package = { version = ">=1.0.0", index = "cloudrepo" }
company-utils = { version = "*", index = "cloudrepo" }

[[project.pypi-indices]]
name = "cloudrepo"
url = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple"
priority = "supplemental"

Authentication Setup

Pixi supports multiple authentication methods for private repositories:

Method 1: Environment Variables (Recommended for CI/CD)

Authentication via Environment Variables

export PIXI_PYPI_USERNAME_CLOUDREPO="[repository-user-email]"
export PIXI_PYPI_PASSWORD_CLOUDREPO="[repository-user-password]"

# Or for Windows PowerShell
$env:PIXI_PYPI_USERNAME_CLOUDREPO = "[repository-user-email]"
$env:PIXI_PYPI_PASSWORD_CLOUDREPO = "[repository-user-password]"

Method 2: URL Authentication (Quick Setup)

pixi.toml - URL-based Authentication

[[project.pypi-indices]]
name = "cloudrepo"
url = "https://[repository-user-email]:[repository-user-password]@[organization-id].mycloudrepo.io/repositories/[repository-id]/simple"

Warning

URL-based authentication embeds credentials in the configuration file. Use environment variables or keyring for production environments.

Method 3: Keyring Integration (Most Secure for Development)

Using System Keyring for Credentials

# Install keyring support
pixi add keyring

# Store credentials in system keyring
python -m keyring set https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple [repository-user-email]
# You'll be prompted for the password

Method 4: .netrc File (Unix-like Systems)

~/.netrc Configuration

machine [organization-id].mycloudrepo.io
login [repository-user-email]
password [repository-user-password]

Secure .netrc Permissions

chmod 600 ~/.netrc

Multiple Index Configuration

Configure Pixi to use multiple package indices efficiently:

pixi.toml - Multiple PyPI Indices

[project]
name = "multi-index-project"
channels = ["conda-forge"]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

# Define multiple PyPI indices
[[project.pypi-indices]]
name = "pypi"
url = "https://pypi.org/simple"
priority = "primary"  # Check PyPI first for public packages

[[project.pypi-indices]]
name = "cloudrepo"
url = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple"
priority = "supplemental"  # Check for packages not on PyPI

[[project.pypi-indices]]
name = "cloudrepo-ml"  # Specialized ML package repository
url = "https://[organization-id].mycloudrepo.io/repositories/[ml-repository-id]/simple"
priority = "explicit"  # Only use when explicitly specified

[pypi-dependencies]
# From PyPI (primary index)
numpy = ">=1.24.0"
scipy = "*"

# From CloudRepo (found via supplemental)
company-core = ">=2.0.0"

# Explicitly from specific index
ml-toolkit = { version = ">=1.0.0", index = "cloudrepo-ml" }

Publishing Packages for Pixi

Building Python Packages

Create a standard Python package structure for publishing:

Package Directory Structure

my-package/
├── pyproject.toml      # Package configuration
├── pixi.toml          # Pixi environment configuration
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
├── tests/
│   └── test_module.py
└── README.md

Configure your package’s pyproject.toml:

pyproject.toml - Package Configuration

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-package"
version = "1.0.0"
description = "Private package for our team"
authors = [{name = "Your Team", email = "team@example.com"}]
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
]

Build the package:

Building Packages with Pixi

# Add build dependencies
pixi add --pypi build twine

# Build the package
pixi run python -m build

# This creates:
# dist/my_package-1.0.0-py3-none-any.whl
# dist/my_package-1.0.0.tar.gz

Publishing to CloudRepo

Upload your package to CloudRepo using twine:

Publishing to CloudRepo

# Configure .pypirc for CloudRepo
cat > ~/.pypirc << EOF
[distutils]
index-servers = cloudrepo

[cloudrepo]
repository = https://[organization-id].mycloudrepo.io/repositories/[repository-id]
username = [repository-user-email]
password = [repository-user-password]
EOF

# Upload the package
pixi run twine upload -r cloudrepo dist/*

# Or upload with inline credentials
pixi run twine upload \
  --repository-url https://[organization-id].mycloudrepo.io/repositories/[repository-id] \
  --username [repository-user-email] \
  --password [repository-user-password] \
  dist/*

Platform-Specific Packages

Build and publish platform-specific packages with binary extensions:

pixi.toml - Platform-Specific Build Configuration

[project]
name = "native-extension"
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

[dependencies]
python = "3.11.*"
cython = ">=3.0.0"
numpy = ">=1.24.0"

[tasks]
build-extension = "python setup.py build_ext --inplace"
build-wheel = { cmd = "python -m build --wheel", depends_on = ["build-extension"] }

# Platform-specific build tasks
[target.win-64.tasks]
build-wheel = "python -m build --wheel --plat-name win_amd64"

[target.linux-64.tasks]
build-wheel = "python -m build --wheel --plat-name manylinux2014_x86_64"

[target.osx-arm64.tasks]
build-wheel = "python -m build --wheel --plat-name macosx_11_0_arm64"

Build for all platforms:

Multi-Platform Build Process

# Build for current platform
pixi run build-wheel

# Or use cibuildwheel for comprehensive platform support
pixi add --pypi cibuildwheel
pixi run cibuildwheel --platform linux

# Upload all platform wheels
pixi run twine upload -r cloudrepo dist/*.whl

Version Management

Manage package versions effectively:

Version Management with Pixi

# Install bump2version for version management
pixi add --pypi bump2version

# Configure version bumping in setup.cfg
cat > setup.cfg << EOF
[bumpversion]
current_version = 1.0.0
commit = True
tag = True

[bumpversion:file:pyproject.toml]
search = version = "{current_version}"
replace = version = "{new_version}"
EOF

# Bump versions
pixi run bump2version patch  # 1.0.0 -> 1.0.1
pixi run bump2version minor  # 1.0.1 -> 1.1.0
pixi run bump2version major  # 1.1.0 -> 2.0.0

# Pre-release versions
pixi run bump2version --new-version 2.0.0-alpha.1 prerelease
pixi run bump2version --new-version 2.0.0-beta.1 prerelease
pixi run bump2version --new-version 2.0.0-rc.1 prerelease

Consuming Packages from CloudRepo

Adding Private Dependencies

Add CloudRepo packages to your Pixi project:

Adding Private Dependencies

# Add a private package from CloudRepo
pixi add --pypi my-private-package --index cloudrepo

# Add with version constraints
pixi add --pypi "my-private-package>=2.0.0,<3.0.0" --index cloudrepo

# Add to specific feature/environment
pixi add --pypi my-dev-tools --index cloudrepo --feature dev

Alternatively, manually edit pixi.toml:

pixi.toml - Private Dependencies

[pypi-dependencies]
# Simple private dependency
my-private-lib = { version = "*", index = "cloudrepo" }

# With version constraints
company-framework = { version = ">=2.0,<3.0", index = "cloudrepo" }

# With extras
ml-toolkit = { version = ">=1.0.0", extras = ["gpu", "viz"], index = "cloudrepo" }

# Pre-release versions
experimental-lib = { version = ">=1.0.0a1", index = "cloudrepo" }

Mixing Public and Private Indices

Efficiently combine packages from multiple sources:

pixi.toml - Mixed Dependencies Configuration

[project]
name = "mixed-dependencies"
channels = ["conda-forge", "pytorch"]
platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"]

# Conda dependencies (from conda-forge/pytorch)
[dependencies]
python = "3.11.*"
pytorch = ">=2.0.0"
cudatoolkit = "11.8.*"  # Platform-specific, managed by conda

# PyPI dependencies
[pypi-dependencies]
# Public packages (from PyPI)
transformers = ">=4.30.0"
datasets = "*"

# Private packages (from CloudRepo)
company-ml-utils = { version = ">=2.0.0", index = "cloudrepo" }
internal-datasets = { version = "*", index = "cloudrepo" }

# Mixed - public package with private plugin
fastapi = ">=0.100.0"  # From PyPI
fastapi-company-auth = { version = ">=1.0.0", index = "cloudrepo" }  # Private auth plugin

Lock File Management

Pixi automatically manages lock files for reproducible environments:

Lock File Management

# Install dependencies and create/update lock file
pixi install

# Update all dependencies to latest compatible versions
pixi update

# Update specific packages only
pixi update numpy pandas my-private-package

# Show current lock file status
pixi list

# Clean and regenerate lock file
pixi clean
pixi install

The pixi.lock file ensures all team members and CI/CD systems get identical dependencies:

pixi.lock Structure (Example)

version: 4
environments:
  default:
    channels:
      - conda-forge
    packages:
      linux-64:
        - python: 3.11.0
        - numpy: 1.24.0
    pypi:
      - my-private-package:
          version: 2.1.0
          index: cloudrepo
          hash: sha256:abc123...

Note

Always commit pixi.lock to version control for reproducible builds.

Environment Specifications

Define multiple environments for different use cases:

pixi.toml - Multiple Environments

[project]
name = "multi-env-project"
channels = ["conda-forge"]
platforms = ["linux-64", "win-64", "osx-64"]

# Default environment dependencies
[dependencies]
python = "3.11.*"

[pypi-dependencies]
requests = "*"
my-core-lib = { version = ">=1.0.0", index = "cloudrepo" }

# Development environment
[feature.dev.dependencies]
pytest = ">=7.0.0"
black = ">=22.0.0"

[feature.dev.pypi-dependencies]
my-test-utils = { version = "*", index = "cloudrepo" }
pytest-cov = "*"

# Production environment
[feature.prod.dependencies]
gunicorn = "*"

[feature.prod.pypi-dependencies]
my-prod-monitor = { version = ">=2.0.0", index = "cloudrepo" }

# Data science environment
[feature.datascience.dependencies]
jupyter = "*"
scikit-learn = "*"

[feature.datascience.pypi-dependencies]
company-ml-lib = { version = ">=3.0.0", index = "cloudrepo" }

# Define environment combinations
[environments]
dev = ["dev"]
prod = ["prod"]
datascience = ["dev", "datascience"]

Activate and use environments:

Working with Environments

# Install default environment
pixi install

# Install specific environment
pixi install -e dev
pixi install -e prod
pixi install -e datascience

# Run commands in specific environment
pixi run -e dev pytest
pixi run -e prod gunicorn app:main
pixi run -e datascience jupyter notebook

# Shell into environment
pixi shell -e dev

Advanced Topics

Multi-Project Workspaces

Manage multiple related projects in a workspace:

Workspace Directory Structure

my-workspace/
├── pixi.toml           # Workspace configuration
├── pixi.lock
├── packages/
│   ├── core-lib/
│   │   ├── pyproject.toml
│   │   └── src/
│   ├── web-api/
│   │   ├── pyproject.toml
│   │   └── src/
│   └── cli-tool/
│       ├── pyproject.toml
│       └── src/
└── apps/
    ├── frontend/
    └── backend/

Workspace pixi.toml configuration:

Workspace pixi.toml

[workspace]
name = "my-workspace"
channels = ["conda-forge"]
platforms = ["linux-64", "win-64", "osx-64"]

# Workspace members
members = [
    "packages/core-lib",
    "packages/web-api",
    "packages/cli-tool",
]

# Shared dependencies across workspace
[dependencies]
python = "3.11.*"

[[pypi-indices]]
name = "cloudrepo"
url = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple"

# Workspace-wide tasks
[tasks]
test-all = "pytest packages/*/tests"
build-all = "python -m build packages/*"
publish-all = """
for pkg in packages/*; do
    cd $pkg && pixi run twine upload -r cloudrepo dist/*
    cd ../..
done
"""

Cross-Platform Builds

Configure platform-specific dependencies and builds:

pixi.toml - Cross-Platform Configuration

[project]
name = "cross-platform-app"
platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"]

# Shared dependencies
[dependencies]
python = "3.11.*"

# Platform-specific dependencies
[target.linux-64.dependencies]
gtk = "*"  # Linux-only GUI toolkit

[target.win-64.dependencies]
pywin32 = "*"  # Windows-specific APIs

[target.osx-64.dependencies]
pyobjc = "*"  # macOS framework bindings

[target.osx-arm64.dependencies]
pyobjc = "*"
tensorflow-metal = "*"  # Apple Silicon acceleration

# Platform-specific PyPI packages from CloudRepo
[target.linux-64.pypi-dependencies]
company-linux-drivers = { version = "*", index = "cloudrepo" }

[target.win-64.pypi-dependencies]
company-windows-utils = { version = "*", index = "cloudrepo" }

# Platform-specific build tasks
[target.linux-64.tasks]
build = "gcc -shared -fPIC -o lib.so src/native.c"

[target.win-64.tasks]
build = "cl /LD src\\native.c /Fe:lib.dll"

[target.osx-64.tasks]
build = "clang -shared -o lib.dylib src/native.c"

Build for all platforms:

Cross-Platform Build Commands

# Install for current platform
pixi install

# Build for all platforms using CI
for platform in linux-64 win-64 osx-64 osx-arm64; do
    pixi install --platform $platform
    pixi run --platform $platform build
done

Conda Integration Alongside PyPI

Leverage both conda and PyPI packages effectively:

pixi.toml - Conda and PyPI Integration

[project]
name = "scientific-computing"
channels = ["conda-forge", "bioconda", "pytorch"]
platforms = ["linux-64", "osx-64"]

# Complex binary dependencies from conda
[dependencies]
python = "3.11.*"
numpy = ">=1.24.0"  # Optimized builds from conda
scipy = "*"
pytorch = ">=2.0.0"
cudatoolkit = "11.8.*"
mkl = "*"  # Intel Math Kernel Library
gdal = "*"  # Geospatial libraries
r-base = ">=4.0"  # R language support

# Python-only packages from PyPI/CloudRepo
[pypi-dependencies]
# Public PyPI packages
pandas = ">=2.0.0"
scikit-learn = "*"

# Private CloudRepo packages
company-ml-models = { version = ">=3.0.0", index = "cloudrepo" }
internal-bio-tools = { version = "*", index = "cloudrepo" }

# Use conda for system dependencies, PyPI for Python packages
[feature.bioinfo.dependencies]
blast = "*"  # NCBI BLAST from bioconda
samtools = "*"
bedtools = "*"

[feature.bioinfo.pypi-dependencies]
biopython = "*"
company-genomics = { version = ">=1.0.0", index = "cloudrepo" }

Task Runners and Scripts

Define reusable tasks in your Pixi configuration:

pixi.toml - Task Configuration

[project]
name = "task-runner-example"

[tasks]
# Simple tasks
test = "pytest tests/"
lint = "ruff check src/"
format = "black src/ tests/"

# Complex multi-step tasks
ci = { depends_on = ["lint", "test", "build"] }

# Tasks with arguments
test-verbose = "pytest -vvs tests/"
test-coverage = "pytest --cov=src --cov-report=html"

# Shell scripts
deploy = """
echo "Building package..."
python -m build
echo "Uploading to CloudRepo..."
twine upload -r cloudrepo dist/*
echo "Deployment complete!"
"""

# Python scripts
process-data = { cmd = "python scripts/process.py", inputs = ["data/*.csv"], outputs = ["processed/"] }

# Platform-specific tasks
[target.linux-64.tasks]
system-info = "uname -a && lscpu"

[target.win-64.tasks]
system-info = "systeminfo"

# Environment-specific tasks
[feature.dev.tasks]
watch = "watchdog src/ --command='pixi run test'"
debug = "python -m pdb src/main.py"

[feature.prod.tasks]
start-server = "gunicorn app:main --bind 0.0.0.0:8000"
health-check = "curl http://localhost:8000/health"

Execute tasks:

Running Pixi Tasks

# Run single task
pixi run test
pixi run lint

# Run task with dependencies
pixi run ci  # Runs lint, test, and build in order

# Run environment-specific task
pixi run -e dev watch
pixi run -e prod start-server

# Pass arguments to tasks
pixi run test -- --maxfail=1
pixi run python -- script.py --arg value

Features and Environments

Create flexible feature combinations:

pixi.toml - Advanced Features Configuration

[project]
name = "feature-example"

# Base dependencies
[dependencies]
python = "3.11.*"

[pypi-dependencies]
core-lib = { version = ">=1.0.0", index = "cloudrepo" }

# Testing feature
[feature.test.dependencies]
pytest = ">=7.0.0"

[feature.test.pypi-dependencies]
pytest-cov = "*"
test-fixtures = { version = "*", index = "cloudrepo" }

[feature.test.tasks]
test = "pytest"
test-ci = "pytest --junitxml=report.xml"

# Documentation feature
[feature.docs.dependencies]
sphinx = ">=5.0.0"

[feature.docs.pypi-dependencies]
company-sphinx-theme = { version = ">=1.0.0", index = "cloudrepo" }

[feature.docs.tasks]
build-docs = "sphinx-build docs/ docs/_build"
serve-docs = "python -m http.server --directory docs/_build"

# GPU feature
[feature.gpu.dependencies]
cuda = "11.8.*"
cudnn = "8.9.*"

[feature.gpu.pypi-dependencies]
torch = { version = ">=2.0.0", index = "pytorch" }
company-gpu-utils = { version = "*", index = "cloudrepo" }

# CPU-only feature (mutual exclusive with gpu)
[feature.cpu.pypi-dependencies]
torch = { version = ">=2.0.0+cpu", index = "pytorch-cpu" }

# Define environment combinations
[environments]
default = []
test = ["test"]
docs = ["docs"]
dev = ["test", "docs"]
gpu-dev = ["test", "gpu"]
cpu-dev = ["test", "cpu"]
prod-gpu = ["gpu"]
prod-cpu = ["cpu"]

Use different feature combinations:

Working with Features

# Install specific environment
pixi install -e gpu-dev
pixi install -e cpu-dev

# Run in specific environment
pixi run -e gpu-dev python train_model.py
pixi run -e docs build-docs

# List available environments
pixi info

# Clean specific environment
pixi clean -e test

CI/CD Integration

GitHub Actions

.github/workflows/pixi-package.yml

name: Pixi Package CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  release:
    types: [published]

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python: ["3.9", "3.10", "3.11"]

    runs-on: ${{ matrix.os }}

    steps:
    - uses: actions/checkout@v4

    - name: Setup Pixi
      uses: prefix-dev/setup-pixi@v0.4.0
      with:
        pixi-version: latest
        cache: true
        cache-dependency-path: pixi.lock

    - name: Configure CloudRepo Authentication
      env:
        PIXI_PYPI_USERNAME_CLOUDREPO: ${{ secrets.CLOUDREPO_USERNAME }}
        PIXI_PYPI_PASSWORD_CLOUDREPO: ${{ secrets.CLOUDREPO_PASSWORD }}
      run: |
        echo "CloudRepo authentication configured via environment variables"

    - name: Install Dependencies
      run: pixi install -e test

    - name: Run Tests
      run: pixi run -e test test-ci

    - name: Upload Test Results
      uses: actions/upload-artifact@v3
      if: always()
      with:
        name: test-results-${{ matrix.os }}-${{ matrix.python }}
        path: report.xml

  build:
    needs: test
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Setup Pixi
      uses: prefix-dev/setup-pixi@v0.4.0
      with:
        pixi-version: latest

    - name: Build Package
      run: |
        pixi run python -m build

    - name: Upload Build Artifacts
      uses: actions/upload-artifact@v3
      with:
        name: dist
        path: dist/

  publish:
    needs: build
    runs-on: ubuntu-latest
    if: github.event_name == 'release'

    steps:
    - uses: actions/checkout@v4

    - name: Download Build Artifacts
      uses: actions/download-artifact@v3
      with:
        name: dist
        path: dist/

    - name: Setup Pixi
      uses: prefix-dev/setup-pixi@v0.4.0

    - name: Configure PyPI Publishing
      run: |
        cat > ~/.pypirc << EOF
        [distutils]
        index-servers = cloudrepo

        [cloudrepo]
        repository = https://${{ secrets.CLOUDREPO_ORG }}.mycloudrepo.io/repositories/${{ secrets.CLOUDREPO_REPO }}
        username = ${{ secrets.CLOUDREPO_USERNAME }}
        password = ${{ secrets.CLOUDREPO_PASSWORD }}
        EOF

    - name: Publish to CloudRepo
      run: |
        pixi add --pypi twine
        pixi run twine upload -r cloudrepo dist/*

GitLab CI

.gitlab-ci.yml

stages:
  - test
  - build
  - publish

variables:
  PIXI_PYPI_USERNAME_CLOUDREPO: ${CLOUDREPO_USERNAME}
  PIXI_PYPI_PASSWORD_CLOUDREPO: ${CLOUDREPO_PASSWORD}
  PIXI_CACHE_DIR: ${CI_PROJECT_DIR}/.pixi_cache

default:
  image: ghcr.io/prefix-dev/pixi:latest
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - .pixi_cache/
      - .pixi/

test:linux:
  stage: test
  script:
    - pixi install -e test
    - pixi run -e test test-ci
  artifacts:
    when: always
    reports:
      junit: report.xml

test:windows:
  stage: test
  tags:
    - windows
  script:
    - pixi install -e test
    - pixi run -e test test-ci

build:
  stage: build
  script:
    - pixi install
    - pixi run python -m build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

publish:
  stage: publish
  only:
    - tags
  dependencies:
    - build
  script:
    - pixi add --pypi twine
    - |
      cat > ~/.pypirc << EOF
      [distutils]
      index-servers = cloudrepo

      [cloudrepo]
      repository = ${CLOUDREPO_URL}
      username = ${CLOUDREPO_USERNAME}
      password = ${CLOUDREPO_PASSWORD}
      EOF
    - pixi run twine upload -r cloudrepo dist/*

Azure DevOps

azure-pipelines.yml

trigger:
  branches:
    include:
      - main
      - develop
  tags:
    include:
      - v*

pool:
  vmImage: 'ubuntu-latest'

variables:
  PIXI_PYPI_USERNAME_CLOUDREPO: $(CloudRepoUsername)
  PIXI_PYPI_PASSWORD_CLOUDREPO: $(CloudRepoPassword)

stages:
- stage: Test
  jobs:
  - job: TestMatrix
    strategy:
      matrix:
        Linux_Python39:
          imageName: 'ubuntu-latest'
          pythonVersion: '3.9'
        Windows_Python311:
          imageName: 'windows-latest'
          pythonVersion: '3.11'
        macOS_Python310:
          imageName: 'macOS-latest'
          pythonVersion: '3.10'
    pool:
      vmImage: $(imageName)
    steps:
    - task: UsePythonVersion@0
      inputs:
        versionSpec: '$(pythonVersion)'

    - script: |
        curl -fsSL https://pixi.sh/install.sh | bash
        echo "##vso[task.prependpath]$HOME/.pixi/bin"
      displayName: 'Install Pixi'
      condition: ne(variables['Agent.OS'], 'Windows_NT')

    - pwsh: |
        iwr -useb https://pixi.sh/install.ps1 | iex
        echo "##vso[task.prependpath]$env:USERPROFILE\.pixi\bin"
      displayName: 'Install Pixi (Windows)'
      condition: eq(variables['Agent.OS'], 'Windows_NT')

    - script: |
        pixi install -e test
        pixi run -e test test-ci
      displayName: 'Run Tests'

    - task: PublishTestResults@2
      inputs:
        testResultsFiles: 'report.xml'
        testRunTitle: 'Python $(pythonVersion) - $(Agent.OS)'
      condition: always()

- stage: Build
  dependsOn: Test
  jobs:
  - job: BuildPackage
    steps:
    - script: |
        curl -fsSL https://pixi.sh/install.sh | bash
        export PATH="$HOME/.pixi/bin:$PATH"
        pixi install
        pixi run python -m build
      displayName: 'Build Package'

    - task: PublishPipelineArtifact@1
      inputs:
        targetPath: 'dist'
        artifactName: 'packages'

- stage: Publish
  dependsOn: Build
  condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/tags/v'))
  jobs:
  - job: PublishToCloudRepo
    steps:
    - task: DownloadPipelineArtifact@2
      inputs:
        artifactName: 'packages'
        targetPath: 'dist'

    - script: |
        curl -fsSL https://pixi.sh/install.sh | bash
        export PATH="$HOME/.pixi/bin:$PATH"
        pixi add --pypi twine

        cat > ~/.pypirc << EOF
        [distutils]
        index-servers = cloudrepo

        [cloudrepo]
        repository = $(CloudRepoUrl)
        username = $(CloudRepoUsername)
        password = $(CloudRepoPassword)
        EOF

        pixi run twine upload -r cloudrepo dist/*
      displayName: 'Publish to CloudRepo'

Troubleshooting

Common Issues and Solutions

Authentication Failures

Debugging Authentication Issues

# Check environment variables
env | grep PIXI_PYPI

# Test authentication directly
curl -u [email]:[password] \
  https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple/

# Clear Pixi cache and retry
pixi clean
pixi install

# Use verbose mode for debugging
PIXI_VERBOSITY=3 pixi install

SSL/TLS Certificate Issues

Resolving SSL Issues

# For self-signed certificates (development only)
export PIXI_SSL_NO_VERIFY=true

# Add corporate CA certificate
export SSL_CERT_FILE=/path/to/ca-bundle.crt
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt

# Configure git for corporate certificates
git config --global http.sslCAInfo /path/to/ca-bundle.crt

Package Resolution Conflicts

Debugging Package Conflicts

# Show detailed solver information
PIXI_VERBOSITY=3 pixi install

# Clean all caches and reinstall
pixi clean --all
rm pixi.lock
pixi install

# Show dependency tree
pixi list --explicit

# Update specific packages only
pixi update numpy pandas

# Force reinstall
pixi install --force-reinstall

Platform-Specific Issues

Platform-Specific Debugging

# Check current platform
pixi info

# Install for specific platform
pixi install --platform linux-64

# List platform-specific packages
pixi list --platform win-64

# Clear platform-specific cache
pixi clean --platform osx-arm64

Index Priority Issues

Fixing Index Priority Problems

# Ensure correct priority order
[[project.pypi-indices]]
name = "cloudrepo"
url = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple"
priority = "primary"  # Check CloudRepo first

[[project.pypi-indices]]
name = "pypi"
url = "https://pypi.org/simple"
priority = "supplemental"  # Fallback to PyPI

Lock File Corruption

Fixing Lock File Issues

# Backup current lock file
cp pixi.lock pixi.lock.backup

# Remove and regenerate
rm pixi.lock
pixi install

# Compare with backup if needed
diff pixi.lock pixi.lock.backup

# Update lock without installing
pixi lock

Slow Package Downloads

Improving Download Performance

# Use parallel downloads
export PIXI_MAX_WORKERS=10

# Configure timeout
export PIXI_REQUEST_TIMEOUT=60

# Use local cache server (if available)
export PIP_INDEX_URL=http://local-cache:8080/simple
export PIP_TRUSTED_HOST=local-cache

# Pre-download packages for offline use
pixi install --frozen
pixi list --json > packages.json

Best Practices

Version Control: Always commit both pixi.toml and pixi.lock files
Environment Isolation: Use features and environments for different contexts
Security: Never commit credentials; use environment variables or keyring
Cross-Platform: Test on all target platforms before releasing
Caching: Leverage Pixi’s caching in CI/CD for faster builds
Documentation: Document custom indices and authentication in README
Updates: Regularly update dependencies with pixi update
Reproducibility: Use pixi install --frozen in production

Performance Tips

Index Configuration: Place CloudRepo as primary index if most packages are private
Parallel Installation: Enable with PIXI_MAX_WORKERS environment variable
Cache Management: Use pixi clean periodically to manage disk space
Minimal Dependencies: Use features to avoid installing unnecessary packages
Platform-Specific Builds: Build native extensions per platform for best performance

Getting Help

If you encounter issues not covered in this documentation:

Check the Pixi documentation
Review CloudRepo’s Knowledge Base
Visit the Pixi Discord community
Contact CloudRepo support at support@cloudrepo.io

CloudRepo support is included with all plans - we typically respond within a few business hours and are here to help you succeed with your cross-platform package management.