WATonomous APT Repository

Central Debian package repository for WATonomous projects, hosted via GitHub Pages.

Overview

This repository serves as a centralized APT repository where all WATonomous projects can publish their Debian packages. The repository is hosted using GitHub Pages and can be accessed at:

https://apt.watonomous.ca

Architecture

┌─────────────────┐
│   project-a     │─┐
│ (source repo)   │ │
└─────────────────┘ │
                    │
┌─────────────────┐ │    ┌──────────────────────┐
│   project-b     │─┼───▶│ wato_apt_repository  │
│ (source repo)   │ │    │    (GitHub Pages)    │
└─────────────────┘ │    └──────────────────────┘
                    │              │
┌─────────────────┐ │              ▼
│   project-c     │─┘         ┌─────────┐
│ (source repo)   │           │  Users  │
└─────────────────┘           └─────────┘

Each source repository builds its .deb packages and pushes them to this central repository via GitHub Actions. Users can then install all WATonomous packages from a single APT source.

For Users

Adding the Repository

To use this repository on Ubuntu/Debian systems:

# Download and add the GPG key
curl -fsSL https://apt.watonomous.ca/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/watonomous-archive-keyring.gpg > /dev/null

# Add the repository
echo "deb [signed-by=/usr/share/keyrings/watonomous-archive-keyring.gpg] https://apt.watonomous.ca stable main" | \
  sudo tee /etc/apt/sources.list.d/watonomous.list

# Update package lists
sudo apt update

# Install any WATonomous package
sudo apt install <package-name>

Supported Architectures

• amd64 (x86_64)
• arm64 (aarch64)

Browsing Available Packages

# List all packages from the repository
apt-cache search --names-only '' | grep watonomous

# Show package information
apt show <package-name>

# List installed WATonomous packages
dpkg -l | grep watonomous

Repository Setup

For Admins: If you're setting up this repository for the first time, see SETUP.md for complete instructions on:

• Configuring GitHub Pages
• Setting up the PAT token
• Initial deployment and testing

For Developers

Quick Start

To release packages from your repository to this APT repository:

1. Obtain secrets: Obtain the APT_REPO_TOKEN and GPG_PRIVATE_KEYfrom a WATonomous admin

2. Add Workflow: Copy the template workflow to .github/workflows/release.yml in your repository

3. Release: Push a version tag:

   git tag v1.0.0
   git push origin v1.0.0

Your package will automatically be built and published to the APT repository!

Documentation

• SETUP.md - Initial repository and GitHub Pages setup
• RELEASING.md - Guide for setting up automated releases from source repos
• release-templates/workflows/ - Ready-to-use workflow templates including ROS2 bloom releases

Management Scripts

Update Repository Metadata

After adding packages, regenerate the repository metadata:

./scripts/update-repo.sh

This script:

• Scans all packages in pool/main/
• Generates Packages files for each architecture
• Creates the Release file
• Compresses metadata files

Add Package Manually

To manually add a package (useful for testing):

./scripts/add-package.sh path/to/package.deb

This will copy the package to pool/main/ and update the repository metadata.

List Packages

View all packages currently in the repository:

./scripts/list-packages.sh

How It Works

Package Release Flow

1. Developer pushes a version tag to a source repository (e.g., v1.0.0)

2. GitHub Actions triggers in the source repository:

   • Checks out the source code
   • Builds the Debian package
   • Checks out this repository (using PAT from WATonomousAdmin)
   • Copies the .deb file to pool/main/
   • Runs update-repo.sh to regenerate metadata
   • Commits and pushes changes

3. GitHub Pages automatically deploys the updated repository

4. Users can install the new package version with apt update && apt install

Repository Metadata

The repository uses standard Debian repository structure:

• pool/main/ - Contains all .deb files
• dists/stable/main/binary-{arch}/Packages - Package indexes for each architecture
• dists/stable/Release - Main release file with checksums

Troubleshooting

Packages Not Updating

1. Check GitHub Actions logs in your source repository
2. Verify APT_REPO_TOKEN is correctly configured in your repository secrets
3. Ensure update-repo.sh ran successfully
4. Run sudo apt update on your system to refresh

Permission Errors

• Verify the PAT has repo scope permissions
• Check that the APT_REPO_TOKEN secret is properly configured
• Ensure the token hasn't expired (contact WATonomous admin for a refreshed token)

Package Installation Fails

# Check package integrity
dpkg -I pool/main/package.deb

# Test installation locally
sudo dpkg -i pool/main/package.deb
sudo apt-get install -f -y

Security Considerations

GPG Signing

This repository uses GPG signing to verify package authenticity. All Release files are signed with our repository key:

• Key ID: 611A7AA1F93ABE52418AF41E97A8FB33E7A13CE2
• Key Email: [email protected]
• Public Key: Available at https://apt.watonomous.ca/public.key

Users must add our public key when setting up the repository (see installation instructions above).

Additional Security Measures

• Restrict APT_REPO_TOKEN access: Only trusted maintainers should have access
• Review packages before publishing: Verify source code and build logs in GitHub Actions
• Monitor repository changes: Watch for unauthorized commits
• Backup the GPG private key: Store securely offline for disaster recovery