Documentation

How to publish Debian packages to PDA Repo — via CI/CD, REST API, or AI agents (MCP / A2A).

Quick Start (curl)
Gitea Actions CI/CD
REST API Reference
MCP Server (AI Agents)
A2A Protocol (Agent-to-Agent)
Version Retention
APT Client Setup

Quick Start

Upload a .deb package with a single curl command:

curl -X POST https://repo.pda.cz/api/v1/ORG/REPO/upload \
  -H "Authorization: Bearer YOUR_UPLOAD_TOKEN" \
  -F "file=@your-package_1.0.0_amd64.deb"

You need:

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

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_UPLOAD_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.:
          dpkg-deb --build ./debian ./my-package_${{ github.ref_name }}_amd64.deb

      - name: Upload to PDA Repo
        run: |
          curl -fsSL -X POST \
            "https://repo.pda.cz/api/v1/ORG/REPO/upload" \
            -H "Authorization: Bearer ${{ secrets.PDA_UPLOAD_TOKEN }}" \
            -F "file=@./my-package_${{ github.ref_name }}_amd64.deb"

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
`GET`	`/api/v1/{org}/{repo}/packages`	-	List packages (JSON)
`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

A2A Protocol Agent-to-Agent

PDA Repo implements the A2A (Agent-to-Agent) protocol for programmatic access from other AI agents or services.

Discovery

curl https://repo.pda.cz/.well-known/agent.json

Task request

Send a JSON-RPC 2.0 request to POST /a2a with a Bearer token:

curl -X POST https://repo.pda.cz/a2a \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tasks/send",
    "params": {
      "id": "task-1",
      "message": {
        "role": "user",
        "parts": [{
          "type": "data",
          "data": {
            "operation": "list_packages",
            "org": "PDAT",
            "repo": "main"
          }
        }]
      }
    }
  }'

Supported operations

Operation	Required fields	Optional fields
`list_repos`	org	—
`list_packages`	org, repo	name, latest
`create_repo`	org, slug	name, description, public
`delete_repo`	org, repo	—
`create_token`	org, name	scopes
`list_tokens`	org	—
`revoke_token`	org, id	—

Authentication: Authorization: Bearer TOKEN with admin scope (global admin token or org admin token).

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)

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

Specific repository

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

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