Documentation

Publish Debian packages and release binaries to PDA Repo — via CI/CD, REST API, the WebSocket dashboard, or AI agents (MCP).

Contents

Quick Start (curl)
Release Binaries (macOS & Linux)
GoReleaser Integration
Gitea Actions CI/CD
REST API Reference
MCP Server (AI Agents)
Version Retention
APT Client Setup
Source & Docs

Quick Start

Set PDA_REPO_TOKEN in your environment to an upload-scoped token, then run in Bash:

set +x
set -euo pipefail
: "${PDA_REPO_TOKEN:?Set PDA_REPO_TOKEN to an upload-scoped token}"
http_status=$(curl --fail --silent --show-error -o /dev/null -w '%{http_code}' \
  -X POST 'https://repo.pda.cz/api/v1/ORG/REPO/upload' \
  -H @- -F "file=@your-package_1.0.0_amd64.deb" <<<"Authorization: Bearer $PDA_REPO_TOKEN")
case "$http_status" in
  2??) ;;
  *) echo "Upload failed (HTTP $http_status)" >&2; exit 1 ;;
esac

You need:

An organization and repository (create them in the Dashboard)
An upload token with the upload scope

Release Binaries (macOS & Linux)

Distribute pre-built binaries for macOS and Linux without publishing source code. Users install with a single command:

curl -fsSL https://repo.pda.cz/install/ORG/REPO/PACKAGE | bash

The install script automatically detects the operating system and architecture, downloads the correct binary, and installs it to /usr/local/bin.

Upload a release binary

Upload binaries using HTTP PUT with a raw body (not multipart):

curl -X PUT https://repo.pda.cz/ORG/REPO/releases/PACKAGE/1.0.0/package_1.0.0_darwin_arm64.tar.gz \
  -H "Authorization: Bearer YOUR_UPLOAD_TOKEN" \
  --data-binary @./package_1.0.0_darwin_arm64.tar.gz

The tarball should contain the binary at the root level (not in a subdirectory). Upload one file per platform:

Platform	Filename convention
macOS ARM (Apple Silicon)	`pkg_1.0.0_darwin_arm64.tar.gz`
macOS Intel	`pkg_1.0.0_darwin_amd64.tar.gz`
Linux x86_64	`pkg_1.0.0_linux_amd64.tar.gz`
Linux ARM64	`pkg_1.0.0_linux_arm64.tar.gz`

Release API

Method	Endpoint	Auth	Description
`PUT`	`/{org}/{repo}/releases/{pkg}/{ver}/{file}`	upload	Upload a release binary
`GET`	`/{org}/{repo}/releases/{pkg}/{ver}/{file}`	-	Download a release binary
`GET`	`/api/v1/{org}/{repo}/releases/{pkg}`	-	List versions (JSON)
`GET`	`/api/v1/{org}/{repo}/releases/{pkg}/{ver}`	-	List files in version (JSON)
`GET`	`/install/{org}/{repo}/{pkg}`	-	Install script

GoReleaser Integration

If you use GoReleaser, add the following to your .goreleaser.yaml to automatically upload binaries on release:

uploads:
  - name: pda-repo
    target: "https://repo.pda.cz/ORG/REPO/releases/PACKAGE/{{.Version}}/{{.ArtifactName}}"
    method: PUT
    custom_headers:
      Authorization: "Bearer {{.Env.PDA_UPLOAD_TOKEN}}"
    mode: binary
    checksum: true

Set the PDA_UPLOAD_TOKEN environment variable in your CI secrets.

Gitea Actions CI/CD

Automate publishing from Gitea by adding a workflow file. The workflow builds your .deb and uploads it on every tag push.

1. Create an upload token

In the Dashboard, go to your organization, click Tokens, and create a token with the upload scope. Copy the token value.

2. Add the token as a Gitea secret

In your Gitea repository, go to Settings → Actions → Secrets and add:

Name	Value
`PDA_REPO_TOKEN`	your upload token

3. Create the workflow file

Add .gitea/workflows/publish.yml to your repository:

name: Build and publish .deb
on:
  push:
    tags:
      - 'v*'

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

      - name: Build .deb package
        run: |
          # Replace with your actual build command, e.g.:
          mkdir -p dist
          dpkg-deb --build ./debian ./dist/my-package_1.0.0_amd64.deb

      - name: Upload to PDA Repo
        env:
          PDA_REPO_TOKEN: ${{ secrets.PDA_REPO_TOKEN }}
        shell: bash
        run: |
          set +x
          set -euo pipefail
          : "${PDA_REPO_TOKEN:?Set PDA_REPO_TOKEN to an upload-scoped token}"
          shopt -s nullglob
          debs=(dist/*.deb)
          (( ${#debs[@]} )) || { echo 'no .deb in dist/' >&2; exit 1; }
          for deb in "${debs[@]}"; do
            http_status=$(curl --fail --silent --show-error -o /dev/null -w '%{http_code}' \
              -X POST 'https://repo.pda.cz/api/v1/ORG/REPO/upload' \
              -H @- -F "file=@${deb}" <<<"Authorization: Bearer $PDA_REPO_TOKEN")
            case "$http_status" in
              2??) ;;
              *) echo "Upload failed (HTTP $http_status)" >&2; exit 1 ;;
            esac
          done

Tip: Replace ORG and REPO with your organization and repository slugs. The build step depends on your project — the key is producing a .deb file that gets uploaded in the final step.

Variant: publish on every push to main

Change the trigger to build on every push:

on:
  push:
    branches: [main]

REST API Reference

Method	Endpoint	Auth	Description
`POST`	`/api/v1/{org}/{repo}/upload`	upload	Upload a .deb package
`PUT`	`/{org}/{repo}/releases/{pkg}/{ver}/{file}`	upload	Upload a release binary
`GET`	`/api/v1/{org}/{repo}/packages`	-	List packages (JSON)
`GET`	`/api/v1/{org}/{repo}/releases/{pkg}`	-	List release versions
`POST`	`/api/v1/{org}/repos`	admin	Create repository
`GET`	`/api/v1/{org}/repos`	admin	List repositories
`DELETE`	`/api/v1/{org}/repos/{slug}`	admin	Delete repository
`POST`	`/api/v1/{org}/tokens`	admin	Create token
`GET`	`/api/v1/{org}/tokens`	admin	List tokens
`DELETE`	`/api/v1/{org}/tokens/{id}`	admin	Revoke token

Authentication: Authorization: Bearer TOKEN header. Tokens have scopes: upload, read, admin.

Upload response

{
  "success": true,
  "name": "my-package",
  "version": "1.2.0",
  "arch": "amd64",
  "sha256": "abc123...",
  "size": 1024000,
  "repo_url": "https://repo.pda.cz/ORG/REPO/"
}

MCP Server AI Agents

PDA Repo includes an MCP (Model Context Protocol) server, so AI agents like Claude can manage repositories and upload packages directly.

Setup for Claude Code

Add the following to your ~/.claude/mcp.json:

{
  "mcpServers": {
    "pda-repo": {
      "command": "/path/to/pda-mcp",
      "env": {
        "PDA_REPO_URL": "https://repo.pda.cz",
        "PDA_ADMIN_TOKEN": "your-admin-token",
        "PDA_UPLOAD_TOKEN": "your-upload-token"
      }
    }
  }
}

Available MCP tools

Tool	Parameters	Description
`list_repos`	org	List repositories for an organization
`list_packages`	org, repo, [name], [latest]	List packages in a repository
`upload_package`	org, repo, file_path	Upload a .deb by local file path
`create_repo`	org, slug, [name], [description], [public]	Create a new repository
`delete_repo`	org, repo	Delete a repository
`create_token`	org, name, [scopes]	Create an API token
`list_tokens`	org	List tokens (no secrets)
`revoke_token`	org, id	Revoke a token by ID

Build the MCP binary

go build -o pda-mcp ./cmd/mcp

Environment variables

Variable	Default	Description
`PDA_REPO_URL`	`https://repo.pda.cz`	Base URL of the PDA Repo server
`PDA_ADMIN_TOKEN`	—	Admin token for repo/token management
`PDA_UPLOAD_TOKEN`	falls back to admin token	Upload-scoped token for publishing packages

Version Retention

PDA Repo keeps only the latest version of each package per architecture. When you upload a new version, the previous version is automatically removed from both storage and the database.

How it works: When pda-pipe_0.4.0_amd64.deb is uploaded, the old pda-pipe_0.3.0_amd64.deb is deleted automatically. Different architectures are tracked independently — uploading an arm64 build does not affect the amd64 version.

APT Client Setup

All public packages (single source)

curl

sudo curl -fsSL https://repo.pda.cz/public.gpg -o /usr/share/keyrings/pda-repo.gpg
echo "deb [signed-by=/usr/share/keyrings/pda-repo.gpg] https://repo.pda.cz/public stable main" | sudo tee /etc/apt/sources.list.d/pda-repo-public.list
sudo apt update

wget

sudo wget -qO /usr/share/keyrings/pda-repo.gpg https://repo.pda.cz/public.gpg
echo "deb [signed-by=/usr/share/keyrings/pda-repo.gpg] https://repo.pda.cz/public stable main" | sudo tee /etc/apt/sources.list.d/pda-repo-public.list
sudo apt update

Specific repository

curl

sudo curl -fsSL https://repo.pda.cz/public.gpg -o /usr/share/keyrings/pda-repo.gpg
echo "deb [signed-by=/usr/share/keyrings/pda-repo.gpg] https://repo.pda.cz/ORG/REPO stable main" | sudo tee /etc/apt/sources.list.d/ORG-REPO.list
sudo apt update

wget

sudo wget -qO /usr/share/keyrings/pda-repo.gpg https://repo.pda.cz/public.gpg
echo "deb [signed-by=/usr/share/keyrings/pda-repo.gpg] https://repo.pda.cz/ORG/REPO stable main" | sudo tee /etc/apt/sources.list.d/ORG-REPO.list
sudo apt update

Private repository (token auth)

echo "machine repo.pda.cz login token password YOUR_READ_TOKEN" | sudo tee /etc/apt/auth.conf.d/pda-repo.conf
sudo chmod 600 /etc/apt/auth.conf.d/pda-repo.conf

Source & Docs

Source code	Git repository on git.pda.cz
Methodology	Development process, spec lifecycle, milestones
Issues	Bug reports and feature requests