2025-12-11 21:50:42 +00:00
<!DOCTYPE HTML>
< html lang = "en" class = "ayu sidebar-visible" dir = "ltr" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Distribution Process - Provisioning Platform Documentation< / title >
<!-- Custom HTML head -->
< meta name = "description" content = "Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" >
< link rel = "icon" href = "../favicon.svg" >
< link rel = "shortcut icon" href = "../favicon.png" >
< link rel = "stylesheet" href = "../css/variables.css" >
< link rel = "stylesheet" href = "../css/general.css" >
< link rel = "stylesheet" href = "../css/chrome.css" >
< link rel = "stylesheet" href = "../css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "../FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "../fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" id = "highlight-css" href = "../highlight.css" >
< link rel = "stylesheet" id = "tomorrow-night-css" href = "../tomorrow-night.css" >
< link rel = "stylesheet" id = "ayu-highlight-css" href = "../ayu-highlight.css" >
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
< script >
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
< / script >
<!-- Start loading toc.js asap -->
< script src = "../toc.js" > < / script >
< / head >
< body >
< div id = "mdbook-help-container" >
< div id = "mdbook-help-popup" >
< h2 class = "mdbook-help-title" > Keyboard shortcuts< / h2 >
< div >
< p > Press < kbd > ←< / kbd > or < kbd > →< / kbd > to navigate between chapters< / p >
< p > Press < kbd > S< / kbd > or < kbd > /< / kbd > to search in the book< / p >
< p > Press < kbd > ?< / kbd > to show this help< / p >
< p > Press < kbd > Esc< / kbd > to hide this help< / p >
< / div >
< / div >
< / div >
< div id = "body-container" >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script >
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script >
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
< / script >
< input type = "checkbox" id = "sidebar-toggle-anchor" class = "hidden" >
<!-- Hide / unhide sidebar before it is displayed -->
< script >
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
<!-- populated by js -->
< mdbook-sidebar-scrollbox class = "sidebar-scrollbox" > < / mdbook-sidebar-scrollbox >
< noscript >
< iframe class = "sidebar-iframe-outer" src = "../toc.html" > < / iframe >
< / noscript >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" >
< div class = "sidebar-resize-indicator" > < / div >
< / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky" >
< div class = "left-buttons" >
< label id = "sidebar-toggle" class = "icon-button" for = "sidebar-toggle-anchor" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / label >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "default_theme" > Auto< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search (`/`)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "/ s" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
< / div >
< h1 class = "menu-title" > Provisioning Platform Documentation< / h1 >
< div class = "right-buttons" >
< a href = "../print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/provisioning/provisioning-platform" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
< a href = "https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/development/distribution-process.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
< h1 id = "distribution-process-documentation" > < a class = "header" href = "#distribution-process-documentation" > Distribution Process Documentation< / a > < / h1 >
< p > This document provides comprehensive documentation for the provisioning project’ < / p >
< h2 id = "table-of-contents" > < a class = "header" href = "#table-of-contents" > Table of Contents< / a > < / h2 >
< ol >
< li > < a href = "#overview" > Overview< / a > < / li >
< li > < a href = "#distribution-architecture" > Distribution Architecture< / a > < / li >
< li > < a href = "#release-process" > Release Process< / a > < / li >
< li > < a href = "#package-generation" > Package Generation< / a > < / li >
< li > < a href = "#multi-platform-distribution" > Multi-Platform Distribution< / a > < / li >
< li > < a href = "#validation-and-testing" > Validation and Testing< / a > < / li >
< li > < a href = "#release-management" > Release Management< / a > < / li >
< li > < a href = "#rollback-procedures" > Rollback Procedures< / a > < / li >
< li > < a href = "#cicd-integration" > CI/CD Integration< / a > < / li >
< li > < a href = "#troubleshooting" > Troubleshooting< / a > < / li >
< / ol >
< h2 id = "overview" > < a class = "header" href = "#overview" > Overview< / a > < / h2 >
< p > The distribution system provides a comprehensive solution for creating, packaging, and distributing provisioning across multiple platforms with automated release management.< / p >
< p > < strong > Key Features< / strong > :< / p >
< ul >
< li > < strong > Multi-Platform Support< / strong > : Linux, macOS, Windows with multiple architectures< / li >
< li > < strong > Multiple Distribution Variants< / strong > : Complete and minimal distributions< / li >
< li > < strong > Automated Release Pipeline< / strong > : From development to production deployment< / li >
< li > < strong > Package Management< / strong > : Binary packages, container images, and installers< / li >
< li > < strong > Validation Framework< / strong > : Comprehensive testing and validation< / li >
< li > < strong > Rollback Capabilities< / strong > : Safe rollback and recovery procedures< / li >
< / ul >
< p > < strong > Location< / strong > : < code > /src/tools/< / code >
< strong > Main Tool< / strong > : < code > /src/tools/Makefile< / code > and associated Nushell scripts< / p >
< h2 id = "distribution-architecture" > < a class = "header" href = "#distribution-architecture" > Distribution Architecture< / a > < / h2 >
< h3 id = "distribution-components" > < a class = "header" href = "#distribution-components" > Distribution Components< / a > < / h3 >
2026-01-08 09:55:37 +00:00
< pre > < code class = "language-plaintext" > Distribution Ecosystem
2025-12-11 21:50:42 +00:00
├── Core Components
│ ├── Platform Binaries # Rust-compiled binaries
│ ├── Core Libraries # Nushell libraries and CLI
│ ├── Configuration System # TOML configuration files
│ └── Documentation # User and API documentation
├── Platform Packages
│ ├── Archives # TAR.GZ and ZIP files
│ ├── Installers # Platform-specific installers
│ └── Container Images # Docker/OCI images
├── Distribution Variants
│ ├── Complete # Full-featured distribution
│ └── Minimal # Lightweight distribution
└── Release Artifacts
├── Checksums # SHA256/MD5 verification
├── Signatures # Digital signatures
└── Metadata # Release information
2026-01-08 09:55:37 +00:00
```plaintext
### Build Pipeline
```plaintext
Build Pipeline Flow
2025-12-11 21:50:42 +00:00
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Source Code │ -> │ Build Stage │ -> │ Package Stage │
│ │ │ │ │ │
│ - Rust code │ │ - compile- │ │ - create- │
│ - Nushell libs │ │ platform │ │ archives │
│ - KCL schemas │ │ - bundle-core │ │ - build- │
│ - Config files │ │ - validate-kcl │ │ containers │
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
v
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Release Stage │ < - │ Validate Stage │ < - │ Distribute Stage│
│ │ │ │ │ │
│ - create- │ │ - test-dist │ │ - generate- │
│ release │ │ - validate- │ │ distribution │
│ - upload- │ │ package │ │ - create- │
│ artifacts │ │ - integration │ │ installers │
└─────────────────┘ └─────────────────┘ └─────────────────┘
2026-01-08 09:55:37 +00:00
```plaintext
### Distribution Variants
**Complete Distribution**:
- All Rust binaries (orchestrator, control-center, MCP server)
- Full Nushell library suite
- All providers, taskservs, and clusters
- Complete documentation and examples
- Development tools and templates
**Minimal Distribution**:
- Essential binaries only
- Core Nushell libraries
- Basic provider support
- Essential task services
- Minimal documentation
## Release Process
### Release Types
**Release Classifications**:
- **Major Release** (x.0.0): Breaking changes, new major features
- **Minor Release** (x.y.0): New features, backward compatible
- **Patch Release** (x.y.z): Bug fixes, security updates
- **Pre-Release** (x.y.z-alpha/beta/rc): Development/testing releases
### Step-by-Step Release Process
#### 1. Preparation Phase
**Pre-Release Checklist**:
```bash
# Update dependencies and security
2025-12-11 21:50:42 +00:00
cargo update
cargo audit
# Run comprehensive tests
make ci-test
# Update documentation
make docs
# Validate all configurations
make validate-all
2026-01-08 09:55:37 +00:00
```plaintext
**Version Planning**:
```bash
# Check current version
2025-12-11 21:50:42 +00:00
git describe --tags --always
# Plan next version
make status | grep Version
# Validate version bump
nu src/tools/release/create-release.nu --dry-run --version 2.1.0
2026-01-08 09:55:37 +00:00
```plaintext
#### 2. Build Phase
**Complete Build**:
```bash
# Clean build environment
2025-12-11 21:50:42 +00:00
make clean
# Build all platforms and variants
make all
# Validate build output
make test-dist
2026-01-08 09:55:37 +00:00
```plaintext
**Build with Specific Parameters**:
```bash
# Build for specific platforms
2025-12-11 21:50:42 +00:00
make all PLATFORMS=linux-amd64,macos-amd64 VARIANTS=complete
# Build with custom version
make all VERSION=2.1.0-rc1
# Parallel build for speed
make all PARALLEL=true
2026-01-08 09:55:37 +00:00
```plaintext
#### 3. Package Generation
**Create Distribution Packages**:
```bash
# Generate complete distributions
2025-12-11 21:50:42 +00:00
make dist-generate
# Create binary packages
make package-binaries
# Build container images
make package-containers
# Create installers
make create-installers
2026-01-08 09:55:37 +00:00
```plaintext
**Package Validation**:
```bash
# Validate packages
2025-12-11 21:50:42 +00:00
make test-dist
# Check package contents
nu src/tools/package/validate-package.nu packages/
# Test installation
make install
make uninstall
2026-01-08 09:55:37 +00:00
```plaintext
#### 4. Release Creation
**Automated Release**:
```bash
# Create complete release
2025-12-11 21:50:42 +00:00
make release VERSION=2.1.0
# Create draft release for review
make release-draft VERSION=2.1.0
# Manual release creation
nu src/tools/release/create-release.nu \
--version 2.1.0 \
--generate-changelog \
--push-tag \
--auto-upload
2026-01-08 09:55:37 +00:00
```plaintext
**Release Options**:
- `--pre-release`: Mark as pre-release
- `--draft`: Create draft release
- `--generate-changelog`: Auto-generate changelog from commits
- `--push-tag`: Push git tag to remote
- `--auto-upload`: Upload assets automatically
#### 5. Distribution and Notification
**Upload Artifacts**:
```bash
# Upload to GitHub Releases
2025-12-11 21:50:42 +00:00
make upload-artifacts
# Update package registries
make update-registry
# Send notifications
make notify-release
2026-01-08 09:55:37 +00:00
```plaintext
**Registry Updates**:
```bash
# Update Homebrew formula
2025-12-11 21:50:42 +00:00
nu src/tools/release/update-registry.nu \
--registries homebrew \
--version 2.1.0 \
--auto-commit
# Custom registry updates
nu src/tools/release/update-registry.nu \
--registries custom \
--registry-url https://packages.company.com \
--credentials-file ~/.registry-creds
2026-01-08 09:55:37 +00:00
```plaintext
### Release Automation
**Complete Automated Release**:
```bash
# Full release pipeline
2025-12-11 21:50:42 +00:00
make cd-deploy VERSION=2.1.0
# Equivalent manual steps:
make clean
make all VERSION=2.1.0
make create-archives
make create-installers
make release VERSION=2.1.0
make upload-artifacts
make update-registry
make notify-release
2026-01-08 09:55:37 +00:00
```plaintext
## Package Generation
### Binary Packages
**Package Types**:
- **Standalone Archives**: TAR.GZ and ZIP with all dependencies
- **Platform Packages**: DEB, RPM, MSI, PKG with system integration
- **Portable Packages**: Single-directory distributions
- **Source Packages**: Source code with build instructions
**Create Binary Packages**:
```bash
# Standard binary packages
2025-12-11 21:50:42 +00:00
make package-binaries
# Custom package creation
nu src/tools/package/package-binaries.nu \
--source-dir dist/platform \
--output-dir packages/binaries \
--platforms linux-amd64,macos-amd64 \
--format archive \
--compress \
--strip \
--checksum
2026-01-08 09:55:37 +00:00
```plaintext
**Package Features**:
- **Binary Stripping**: Removes debug symbols for smaller size
- **Compression**: GZIP, LZMA, and Brotli compression
- **Checksums**: SHA256 and MD5 verification
- **Signatures**: GPG and code signing support
### Container Images
**Container Build Process**:
```bash
# Build container images
2025-12-11 21:50:42 +00:00
make package-containers
# Advanced container build
nu src/tools/package/build-containers.nu \
--dist-dir dist \
--tag-prefix provisioning \
--version 2.1.0 \
--platforms "linux/amd64,linux/arm64" \
--optimize-size \
--security-scan \
--multi-stage
2026-01-08 09:55:37 +00:00
```plaintext
**Container Features**:
- **Multi-Stage Builds**: Minimal runtime images
- **Security Scanning**: Vulnerability detection
- **Multi-Platform**: AMD64, ARM64 support
- **Layer Optimization**: Efficient layer caching
- **Runtime Configuration**: Environment-based configuration
**Container Registry Support**:
- Docker Hub
- GitHub Container Registry
- Amazon ECR
- Google Container Registry
- Azure Container Registry
- Private registries
### Installers
**Installer Types**:
- **Shell Script Installer**: Universal Unix/Linux installer
- **Package Installers**: DEB, RPM, MSI, PKG
- **Container Installer**: Docker/Podman setup
- **Source Installer**: Build-from-source installer
**Create Installers**:
```bash
# Generate all installer types
2025-12-11 21:50:42 +00:00
make create-installers
# Custom installer creation
nu src/tools/distribution/create-installer.nu \
dist/provisioning-2.1.0-linux-amd64-complete \
--output-dir packages/installers \
--installer-types shell,package \
--platforms linux,macos \
--include-services \
--create-uninstaller \
--validate-installer
2026-01-08 09:55:37 +00:00
```plaintext
**Installer Features**:
- **System Integration**: Systemd/Launchd service files
- **Path Configuration**: Automatic PATH updates
- **User/System Install**: Support for both user and system-wide installation
- **Uninstaller**: Clean removal capability
- **Dependency Management**: Automatic dependency resolution
- **Configuration Setup**: Initial configuration creation
## Multi-Platform Distribution
### Supported Platforms
**Primary Platforms**:
- **Linux AMD64** (x86_64-unknown-linux-gnu)
- **Linux ARM64** (aarch64-unknown-linux-gnu)
- **macOS AMD64** (x86_64-apple-darwin)
- **macOS ARM64** (aarch64-apple-darwin)
- **Windows AMD64** (x86_64-pc-windows-gnu)
- **FreeBSD AMD64** (x86_64-unknown-freebsd)
**Platform-Specific Features**:
- **Linux**: SystemD integration, package manager support
- **macOS**: LaunchAgent services, Homebrew packages
- **Windows**: Windows Service support, MSI installers
- **FreeBSD**: RC scripts, pkg packages
### Cross-Platform Build
**Cross-Compilation Setup**:
```bash
# Install cross-compilation targets
2025-12-11 21:50:42 +00:00
rustup target add aarch64-unknown-linux-gnu
rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin
rustup target add x86_64-pc-windows-gnu
# Install cross-compilation tools
cargo install cross
2026-01-08 09:55:37 +00:00
```plaintext
**Platform-Specific Builds**:
```bash
# Build for specific platform
2025-12-11 21:50:42 +00:00
make build-platform RUST_TARGET=aarch64-apple-darwin
# Build for multiple platforms
make build-cross PLATFORMS=linux-amd64,macos-arm64,windows-amd64
# Platform-specific distributions
make linux
make macos
make windows
2026-01-08 09:55:37 +00:00
```plaintext
### Distribution Matrix
**Generated Distributions**:
```plaintext
Distribution Matrix:
2025-12-11 21:50:42 +00:00
provisioning-{version}-{platform}-{variant}.{format}
Examples:
- provisioning-2.1.0-linux-amd64-complete.tar.gz
- provisioning-2.1.0-macos-arm64-minimal.tar.gz
- provisioning-2.1.0-windows-amd64-complete.zip
- provisioning-2.1.0-freebsd-amd64-minimal.tar.xz
2026-01-08 09:55:37 +00:00
```plaintext
**Platform Considerations**:
- **File Permissions**: Executable permissions on Unix systems
- **Path Separators**: Platform-specific path handling
- **Service Integration**: Platform-specific service management
- **Package Formats**: TAR.GZ for Unix, ZIP for Windows
- **Line Endings**: CRLF for Windows, LF for Unix
## Validation and Testing
### Distribution Validation
**Validation Pipeline**:
```bash
# Complete validation
2025-12-11 21:50:42 +00:00
make test-dist
# Custom validation
nu src/tools/build/test-distribution.nu \
--dist-dir dist \
--test-types basic,integration,complete \
--platform linux \
--cleanup \
--verbose
2026-01-08 09:55:37 +00:00
```plaintext
**Validation Types**:
- **Basic**: Installation test, CLI help, version check
- **Integration**: Server creation, configuration validation
- **Complete**: Full workflow testing including cluster operations
### Testing Framework
**Test Categories**:
- **Unit Tests**: Component-specific testing
- **Integration Tests**: Cross-component testing
- **End-to-End Tests**: Complete workflow testing
- **Performance Tests**: Load and performance validation
- **Security Tests**: Security scanning and validation
**Test Execution**:
```bash
# Run all tests
2025-12-11 21:50:42 +00:00
make ci-test
# Specific test types
nu src/tools/build/test-distribution.nu --test-types basic
nu src/tools/build/test-distribution.nu --test-types integration
nu src/tools/build/test-distribution.nu --test-types complete
2026-01-08 09:55:37 +00:00
```plaintext
### Package Validation
**Package Integrity**:
```bash
# Validate package structure
2025-12-11 21:50:42 +00:00
nu src/tools/package/validate-package.nu dist/
# Check checksums
sha256sum -c packages/checksums.sha256
# Verify signatures
gpg --verify packages/provisioning-2.1.0.tar.gz.sig
2026-01-08 09:55:37 +00:00
```plaintext
**Installation Testing**:
```bash
# Test installation process
2025-12-11 21:50:42 +00:00
./packages/installers/install-provisioning-2.1.0.sh --dry-run
# Test uninstallation
./packages/installers/uninstall-provisioning.sh --dry-run
# Container testing
docker run --rm provisioning:2.1.0 provisioning --version
2026-01-08 09:55:37 +00:00
```plaintext
## Release Management
### Release Workflow
**GitHub Release Integration**:
```bash
# Create GitHub release
2025-12-11 21:50:42 +00:00
nu src/tools/release/create-release.nu \
--version 2.1.0 \
--asset-dir packages \
--generate-changelog \
--push-tag \
--auto-upload
2026-01-08 09:55:37 +00:00
```plaintext
**Release Features**:
- **Automated Changelog**: Generated from git commit history
- **Asset Management**: Automatic upload of all distribution artifacts
- **Tag Management**: Semantic version tagging
- **Release Notes**: Formatted release notes with change summaries
### Versioning Strategy
**Semantic Versioning**:
- **MAJOR.MINOR.PATCH** format (e.g., 2.1.0)
- **Pre-release** suffixes (e.g., 2.1.0-alpha.1, 2.1.0-rc.2)
- **Build metadata** (e.g., 2.1.0+20250925.abcdef)
**Version Detection**:
```bash
# Auto-detect next version
2025-12-11 21:50:42 +00:00
nu src/tools/release/create-release.nu --release-type minor
# Manual version specification
nu src/tools/release/create-release.nu --version 2.1.0
# Pre-release versioning
nu src/tools/release/create-release.nu --version 2.1.0-rc.1 --pre-release
2026-01-08 09:55:37 +00:00
```plaintext
### Artifact Management
**Artifact Types**:
- **Source Archives**: Complete source code distributions
- **Binary Archives**: Compiled binary distributions
- **Container Images**: OCI-compliant container images
- **Installers**: Platform-specific installation packages
- **Documentation**: Generated documentation packages
**Upload and Distribution**:
```bash
# Upload to GitHub Releases
2025-12-11 21:50:42 +00:00
make upload-artifacts
# Upload to container registries
docker push provisioning:2.1.0
# Update package repositories
make update-registry
2026-01-08 09:55:37 +00:00
```plaintext
## Rollback Procedures
### Rollback Scenarios
**Common Rollback Triggers**:
- Critical bugs discovered post-release
- Security vulnerabilities identified
- Performance regression
- Compatibility issues
- Infrastructure failures
### Rollback Process
**Automated Rollback**:
```bash
# Rollback latest release
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu --version 2.1.0
# Rollback with specific target
nu src/tools/release/rollback-release.nu \
--from-version 2.1.0 \
--to-version 2.0.5 \
--update-registries \
--notify-users
2026-01-08 09:55:37 +00:00
```plaintext
**Manual Rollback Steps**:
```bash
# 1. Identify target version
2025-12-11 21:50:42 +00:00
git tag -l | grep -v 2.1.0 | tail -5
# 2. Create rollback release
nu src/tools/release/create-release.nu \
--version 2.0.6 \
--rollback-from 2.1.0 \
--urgent
# 3. Update package managers
nu src/tools/release/update-registry.nu \
--version 2.0.6 \
--rollback-notice "Critical fix for 2.1.0 issues"
# 4. Notify users
nu src/tools/release/notify-users.nu \
--channels slack,discord,email \
--message-type rollback \
--urgent
2026-01-08 09:55:37 +00:00
```plaintext
### Rollback Safety
**Pre-Rollback Validation**:
- Validate target version integrity
- Check compatibility matrix
- Verify rollback procedure testing
- Confirm communication plan
**Rollback Testing**:
```bash
# Test rollback in staging
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu \
--version 2.1.0 \
--target-version 2.0.5 \
--dry-run \
--staging-environment
# Validate rollback success
make test-dist DIST_VERSION=2.0.5
2026-01-08 09:55:37 +00:00
```plaintext
### Emergency Procedures
**Critical Security Rollback**:
```bash
# Emergency rollback (bypasses normal procedures)
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu \
--version 2.1.0 \
--emergency \
--security-issue \
--immediate-notify
2026-01-08 09:55:37 +00:00
```plaintext
**Infrastructure Failure Recovery**:
```bash
# Failover to backup infrastructure
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu \
--infrastructure-failover \
--backup-registry \
--mirror-sync
2026-01-08 09:55:37 +00:00
```plaintext
## CI/CD Integration
### GitHub Actions Integration
**Build Workflow** (`.github/workflows/build.yml`):
```yaml
name: Build and Distribute
2025-12-11 21:50:42 +00:00
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
platform: [linux, macos, windows]
steps:
- uses: actions/checkout@v4
- name: Setup Nushell
uses: hustcer/setup-nu@v3.5
- name: Setup Rust
uses: actions-rs/toolchain@v1
with:
toolchain: stable
- name: CI Build
run: |
cd src/tools
make ci-build
- name: Upload Build Artifacts
uses: actions/upload-artifact@v4
with:
name: build-${{ matrix.platform }}
path: src/dist/
2026-01-08 09:55:37 +00:00
```plaintext
**Release Workflow** (`.github/workflows/release.yml`):
```yaml
name: Release
2025-12-11 21:50:42 +00:00
on:
push:
tags: ['v*']
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build Release
run: |
cd src/tools
make ci-release VERSION=${{ github.ref_name }}
- name: Create Release
run: |
cd src/tools
make release VERSION=${{ github.ref_name }}
- name: Update Registries
run: |
cd src/tools
make update-registry VERSION=${{ github.ref_name }}
2026-01-08 09:55:37 +00:00
```plaintext
### GitLab CI Integration
**GitLab CI Configuration** (`.gitlab-ci.yml`):
```yaml
stages:
2025-12-11 21:50:42 +00:00
- build
- package
- test
- release
build:
stage: build
script:
- cd src/tools
- make ci-build
artifacts:
paths:
- src/dist/
expire_in: 1 hour
package:
stage: package
script:
- cd src/tools
- make package-all
artifacts:
paths:
- src/packages/
expire_in: 1 day
release:
stage: release
script:
- cd src/tools
- make cd-deploy VERSION=${CI_COMMIT_TAG}
only:
- tags
2026-01-08 09:55:37 +00:00
```plaintext
### Jenkins Integration
**Jenkinsfile**:
```groovy
pipeline {
2025-12-11 21:50:42 +00:00
agent any
stages {
stage('Build') {
steps {
dir('src/tools') {
sh 'make ci-build'
}
}
}
stage('Package') {
steps {
dir('src/tools') {
sh 'make package-all'
}
}
}
stage('Release') {
when {
tag '*'
}
steps {
dir('src/tools') {
sh "make cd-deploy VERSION=${env.TAG_NAME}"
}
}
}
}
}
2026-01-08 09:55:37 +00:00
```plaintext
## Troubleshooting
### Common Issues
#### Build Failures
**Rust Compilation Errors**:
```bash
# Solution: Clean and rebuild
2025-12-11 21:50:42 +00:00
make clean
cargo clean
make build-platform
# Check Rust toolchain
rustup show
rustup update
2026-01-08 09:55:37 +00:00
```plaintext
**Cross-Compilation Issues**:
```bash
# Solution: Install missing targets
2025-12-11 21:50:42 +00:00
rustup target list --installed
rustup target add x86_64-apple-darwin
# Use cross for problematic targets
cargo install cross
make build-platform CROSS=true
2026-01-08 09:55:37 +00:00
```plaintext
#### Package Generation Issues
**Missing Dependencies**:
```bash
# Solution: Install build tools
2025-12-11 21:50:42 +00:00
sudo apt-get install build-essential
brew install gnu-tar
# Check tool availability
make info
2026-01-08 09:55:37 +00:00
```plaintext
**Permission Errors**:
```bash
# Solution: Fix permissions
2025-12-11 21:50:42 +00:00
chmod +x src/tools/build/*.nu
chmod +x src/tools/distribution/*.nu
chmod +x src/tools/package/*.nu
2026-01-08 09:55:37 +00:00
```plaintext
#### Distribution Validation Failures
**Package Integrity Issues**:
```bash
# Solution: Regenerate packages
2025-12-11 21:50:42 +00:00
make clean-dist
make package-all
# Verify manually
sha256sum packages/*.tar.gz
2026-01-08 09:55:37 +00:00
```plaintext
**Installation Test Failures**:
```bash
# Solution: Test in clean environment
2025-12-11 21:50:42 +00:00
docker run --rm -v $(pwd):/work ubuntu:latest /work/packages/installers/install.sh
# Debug installation
./packages/installers/install.sh --dry-run --verbose
2026-01-08 09:55:37 +00:00
```plaintext
### Release Issues
#### Upload Failures
**Network Issues**:
```bash
# Solution: Retry with backoff
2025-12-11 21:50:42 +00:00
nu src/tools/release/upload-artifacts.nu \
--retry-count 5 \
--backoff-delay 30
# Manual upload
gh release upload v2.1.0 packages/*.tar.gz
2026-01-08 09:55:37 +00:00
```plaintext
**Authentication Failures**:
```bash
# Solution: Refresh tokens
2025-12-11 21:50:42 +00:00
gh auth refresh
docker login ghcr.io
# Check credentials
gh auth status
docker system info
2026-01-08 09:55:37 +00:00
```plaintext
#### Registry Update Issues
**Homebrew Formula Issues**:
```bash
# Solution: Manual PR creation
2025-12-11 21:50:42 +00:00
git clone https://github.com/Homebrew/homebrew-core
cd homebrew-core
# Edit formula
git add Formula/provisioning.rb
git commit -m "provisioning 2.1.0"
2026-01-08 09:55:37 +00:00
```plaintext
### Debug and Monitoring
**Debug Mode**:
```bash
# Enable debug logging
2025-12-11 21:50:42 +00:00
export PROVISIONING_DEBUG=true
export RUST_LOG=debug
# Run with verbose output
make all VERBOSE=true
# Debug specific components
nu src/tools/distribution/generate-distribution.nu \
--verbose \
--dry-run
2026-01-08 09:55:37 +00:00
```plaintext
**Monitoring Build Progress**:
```bash
# Monitor build logs
2025-12-11 21:50:42 +00:00
tail -f src/tools/build.log
# Check build status
make status
# Resource monitoring
top
df -h
2026-01-08 09:55:37 +00:00
```plaintext
This distribution process provides a robust, automated pipeline for creating, validating, and distributing provisioning across multiple platforms while maintaining high quality and reliability standards.
2025-12-11 21:50:42 +00:00
< / code > < / pre >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2026-01-08 09:55:37 +00:00
< a rel = "prev" href = "../development/extensions.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../development/implementation-guide.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
2026-01-08 09:55:37 +00:00
< a rel = "prev" href = "../development/extensions.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../development/implementation-guide.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script >
window.playground_copyable = true;
< / script >
< script src = "../elasticlunr.min.js" > < / script >
< script src = "../mark.min.js" > < / script >
< script src = "../searcher.js" > < / script >
< script src = "../clipboard.min.js" > < / script >
< script src = "../highlight.js" > < / script >
< script src = "../book.js" > < / script >
<!-- Custom JS scripts -->
< / div >
< / body >
< / html >
