CI/CD Integration Guide

Overview

DistroPack provides comprehensive CI/CD integration capabilities through API token authentication. This enables automated package building and distribution directly from your CI/CD pipelines.

The integration flow is simple:

1. Create an API token in your dashboard
2. Configure your CI/CD pipeline with the token
3. Upload files and trigger builds automatically

Getting Started

Step 1: Create an API Token

First, create an API token from your dashboard. Navigate to API Tokens and create a new token with a descriptive name (e.g., "GitHub Actions CI/CD").

Step 2: Configure Your CI/CD Pipeline

Add your API token as a secret in your CI/CD platform:

• GitHub Actions: Add as a repository secret named DISTROPACK_API_TOKEN
• GitLab CI: Add as a CI/CD variable (masked) named DISTROPACK_API_TOKEN
• CircleCI: Add as an environment variable in project settings
• Other platforms: Use environment variables or secret management

Step 3: Use the DistroPack CLI or GitHub Action

You can integrate DistroPack in two ways:

• GitHub Action (Recommended): Use the official distropack/distropack-action@v1.0 action
• CLI: Install and use the DistroPack CLI directly

GitHub Actions Example

Here's a complete example workflow for GitHub Actions:

name: Build and Package

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build application
        run: |
          # Your build steps here
          tar -czf dist/app.tar.gz build/

      - name: DistroPack
        uses: distropack/distropack-action@v1.0
        with:
          api-token: ${{ secrets.DISTROPACK_API_TOKEN }}
          package-id: your-package-id
          version: ${{ github.ref_name }}
          files: |
            {
              "source-tarball": "dist/app.tar.gz",
              "changelog": "CHANGELOG.md"
            }

CLI Example

If you prefer using the CLI directly:

# Install CLI
cargo install distropack-cli --locked

# Set API token
export DISTROPACK_API_TOKEN="your-token-here"

# Upload files
distropack-cli upload --package-id your-package-id --ref-id source-tarball --file dist/app.tar.gz
distropack-cli upload --package-id your-package-id --ref-id changelog --file CHANGELOG.md
# Trigger build
distropack-cli build --package-id your-package-id --version 1.0.0

API Endpoints

All API endpoints require authentication via Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Available endpoints:

• POST /api/upload_file - Upload files to packages
• POST /api/build_package - Trigger builds for all enabled targets
• POST /api/build_package_single - Build for a specific distribution

For detailed API documentation, see the API Tokens page.

Security Best Practices

• Never commit tokens to version control
• Use secrets management in your CI/CD platform
• Rotate tokens regularly for better security
• Use separate tokens for different environments (dev, staging, production)
• Delete unused tokens to minimize attack surface

Troubleshooting

Authentication Issues

• Verify your token is set correctly in environment variables
• Check that the token hasn't been revoked
• Ensure your account has an active subscription

Upload Failures

• Verify file paths are correct
• Check file permissions
• Ensure reference IDs match your package configuration

Build Failures

• Check that all required files have been uploaded
• Verify the version is newer than the last successful build
• Ensure at least one build target is enabled

Additional Resources