Skip to content

Add support for architecture variants - #1638

Merged
neolynx merged 16 commits into
aptly-dev:masterfrom
hjmitsd:architecture-variants
Nov 6, 2026
Merged

neolynx merged 16 commits into
aptly-dev:masterfrom
hjmitsd:architecture-variants

Conversation

@hjmitsd

@hjmitsd hjmitsd commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Fixes: #793, #1468

Discussion / Request: #1501

Summary

This PR adds support for package architecture variants such as amd64v3.

Ubuntu 26.04 publishes separate indexes such as:

binary-amd64/
binary-amd64v3/

while packages from the variant index still use:

Architecture: amd64
Architecture-Variant: amd64v3

This means a regular package and its architecture variant may have the same name, version and base architecture. Aptly currently treats them as the same package identity.

Approach

The patch introduces the concept of an index architecture:

  • regular package: amd64
  • variant package: amd64v3

The original Architecture: amd64 remains unchanged and continues to be used for dependency matching.

Architecture variants are distinguished only where package or repository identity requires it.

The changes cover:

  • package identity and persistence
  • remote mirrors
  • filtered mirrors and dependency following
  • publishing
  • package queries
  • snapshot diff/pull
  • local repository imports and -force-replace
  • API package handling

Existing packages without Architecture-Variant retain their previous package keys and behavior.

Validation

The implementation was tested with both automated tests and real Ubuntu 26.04 repositories.

A full Ubuntu 26.04 mirror was created for release, updates, security and backports, including main, universe, restricted and multiverse, with both amd64 and amd64v3.

A real Ubuntu 26.04 APT client successfully selected and installed the amd64v3 package when configured with:

APT::Architecture-Variants "amd64v3";

I also tested an in-place upgrade of an existing Aptly mirror database populated by unmodified upstream Aptly. The patched build added the previously discarded amd64v3 packages without requiring a mirror rebuild.

The relevant test suites pass:

go test ./deb
go test ./query
go test ./cmd
go test ./api

The remaining failures from go test ./... are reproducible on the unmodified upstream source and are unrelated to this change.

Additional upstream issues

Two pre-existing issues were found during development and are included as separate commits:

  • API snapshot pull did not fully load the destination snapshot before modifying it.
  • API maximumVersion=1 could collapse packages from different architectures.

Both also affect ordinary non-variant packages.

I can split these into separate PRs if preferred.

Development process

For transparency, I developed this implementation with assistance from OpenAI Codex.

The resulting changes were reviewed and validated with regression tests, real Ubuntu 26.04 repositories, an existing Aptly database and a real APT client.

This is my first contribution to Aptly, so I am happy to adjust the implementation, naming, scope or commit structure to better match the project's conventions.

@codecov

codecov Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.66667% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.62%. Comparing base (f72347a) to head (b6cb4de).
⚠️ Report is 17 commits behind head on master.

Files with missing lines Patch % Lines
api/api.go 25.00% 2 Missing and 1 partial ⚠️
deb/import.go 0.00% 1 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #1638      +/-   ##
==========================================
- Coverage   77.81%   77.62%   -0.19%     
==========================================
  Files         165      165              
  Lines       16125    16141      +16     
==========================================
- Hits        12548    12530      -18     
- Misses       2363     2401      +38     
+ Partials     1214     1210       -4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@neolynx neolynx self-assigned this Oct 12, 2026
@neolynx neolynx added the needs review Ready for review & merge label Oct 12, 2026
@neolynx
neolynx force-pushed the architecture-variants branch from e6efb13 to 9967404 Compare November 1, 2026 09:44
@neolynx

neolynx commented Nov 1, 2026

Copy link
Copy Markdown
Member

rebased on master

@neolynx
neolynx force-pushed the architecture-variants branch from 9967404 to 2818aeb Compare November 1, 2026 09:53
@neolynx neolynx added the feature label Nov 1, 2026
@hjmitsd

hjmitsd commented Nov 1, 2026

Copy link
Copy Markdown
Contributor Author

I tested the rebased PR using the official CI-built Noble/amd64 artifact:

aptly version: 1.6.3+20261101095331.89eee947

The test was performed with our real Ubuntu 26.04 (Resolute) mirror setup.

The complete mirror workflow succeeded for:

resolute

resolute-updates

resolute-security

resolute-backports

with all four components:

main

universe

restricted

multiverse

and with both amd64 and amd64v3.

Our normal production-like workflow completed successfully, including mirror updates, snapshot creation, publish switches, security promotion and snapshot retention.

I also tested the resulting repository with a real Ubuntu 26.04 client.

With:

APT::Architecture-Variants "amd64v3";

APT fetched the amd64v3 package indexes and successfully upgraded 85 real packages from the published repository, including packages such as systemd, SSSD, snapd, PipeWire and GNOME components. The downloaded packages were the expected _amd64v3.deb variants.

I also verified that the publish contains the regular and variant package independently. For example, the same systemd version is published as:

binary-amd64: systemd_259.9-0ubuntu0.1_amd64.deb

and

binary-amd64v3: systemd_259.9-0ubuntu0.1_amd64v3.deb with Architecture-Variant: amd64v3.

Finally, I disabled APT::Architecture-Variants on the client, refreshed the package lists and verified that APT fetched only the regular amd64 indexes and selected:

systemd_259.9-0ubuntu0.1_amd64.deb

So both the architecture-variant path and the normal amd64 fallback work as expected with the rebased CI build.

No issues found in these tests.

@neolynx
neolynx force-pushed the architecture-variants branch from 2818aeb to faa348f Compare November 3, 2026 12:30
@neolynx

neolynx commented Nov 3, 2026

Copy link
Copy Markdown
Member

rebased on master

@neolynx

neolynx commented Nov 3, 2026

Copy link
Copy Markdown
Member

Hi @hjmitsd !

Awesome work 👍

We should add some system tests, I would like to see a real mirror being mirrors with arch variants...

Could you try to add some system tests ? They should just download a handful of packages, in order to be fast (not the whole
ubuntu! ;-)

I will then mirror those packages on repo.aptly.info for the pipeline tests to not depend on changing public repos.

@neolynx
neolynx force-pushed the architecture-variants branch from faa348f to eb76598 Compare November 3, 2026 12:39
@neolynx

neolynx commented Nov 3, 2026

Copy link
Copy Markdown
Member

force pushed to fix rebase typo

@hjmitsd

hjmitsd commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

I have a small system test working locally against the Ubuntu Resolute archive.

It mirrors only one package (3cpio) for amd64 and amd64v3:

distribution: resolute
component: main
architectures: amd64, amd64v3
filter: Name (3cpio)
version: 0.14.0-1ubuntu1

The two package files are:

pool/main/r/rust-threecpio/3cpio_0.14.0-1ubuntu1_amd64.deb
pool/main/r/rust-threecpio/3cpio_0.14.0-1ubuntu1_amd64v3.deb

The test currently uses:

class UpdateMirror29Test(BaseTest):
    """
    update mirrors: architecture variants
    """
    sortOutput = True
    longTest = False
    fixtureCmds = [
        "aptly mirror create --ignore-signatures "
        "-architectures=amd64,amd64v3 "
        "-filter='Name (3cpio)' "
        "arch-variant https://archive.ubuntu.com/ubuntu/ resolute main",
    ]
    runCmd = "aptly mirror update --ignore-signatures arch-variant"

    def check(self):
        self.check_output()
        self.check_cmd_output(
            "aptly mirror search -format='{{.ShortKey}}' "
            "arch-variant 'Name (3cpio)'",
            "packages",
        )

It downloads only the two packages (~0.54 MiB total), and afterwards verifies that both package identities are present independently:

Pamd64 3cpio 0.14.0-1ubuntu1
Pamd64v3 3cpio 0.14.0-1ubuntu1

The system test passes locally both when capturing the golden files and on a clean rerun without capture.

I have not pushed it yet, so I can switch it directly to the repo.aptly.info fixture once it is available.

@neolynx

neolynx commented Nov 4, 2026

Copy link
Copy Markdown
Member

I would need to have the logs "Downloading.." from the test in order to create the test mirror. you can push the test as is, or send me the url list :)

@neolynx

neolynx commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

uploaded:

┌───────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐                                           
│ File                  │ Apt Repo URL                                                                                                               │                                           
|───────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                           
│ Release               │ http://repo.aptly.info/system-tests/archive.ubuntu.com/ubuntu/dists/resolute/Release                                       │                                           
├───────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                           
│ Packages (amd64)      │ http://repo.aptly.info/system-tests/archive.ubuntu.com/ubuntu/dists/resolute/main/binary-amd64/Packages.gz                 │                                           
├───────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                           
│ Packages (amd64v3)    │ http://repo.aptly.info/system-tests/archive.ubuntu.com/ubuntu/dists/resolute/main/binary-amd64v3/Packages.gz               │                                           
├───────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                           
│ 3cpio (.deb, amd64)   │ http://repo.aptly.info/system-tests/archive.ubuntu.com/ubuntu/pool/main/r/rust-threecpio/3cpio_0.14.0-1ubuntu1_amd64.deb   │                                           
├───────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                           
│ 3cpio (.deb, amd64v3) │ http://repo.aptly.info/system-tests/archive.ubuntu.com/ubuntu/pool/main/r/rust-threecpio/3cpio_0.14.0-1ubuntu1_amd64v3.deb │                                           
└───────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘    

@neolynx
neolynx force-pushed the architecture-variants branch from c6a9cc1 to 54fba1c Compare November 5, 2026 19:52
@neolynx

neolynx commented Nov 5, 2026

Copy link
Copy Markdown
Member

renased on master and fixed conflict in deb/list.go by keeping master's grouping approach (which handles invalid versions correctly) and using IndexArchitecture() as the key instead of p.Architecture.

@neolynx
neolynx force-pushed the architecture-variants branch from 54fba1c to b89f92e Compare November 5, 2026 20:01
@neolynx
neolynx force-pushed the architecture-variants branch from b89f92e to 972cf0b Compare November 5, 2026 20:16
@neolynx
neolynx requested a review from a team November 6, 2026 15:34
@neolynx

neolynx commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

@hjmitsd great, we have a system test :)

@neolynx neolynx left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

awesome job, thanks a lot !

@neolynx
neolynx marked this pull request as ready for review November 6, 2026 15:37
@neolynx
neolynx merged commit e35afce into aptly-dev:master Nov 6, 2026
41 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature needs review Ready for review & merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pull and merge have different definitions of "same" architecture

2 participants