Skip to content

Add directory structure explainer #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mattwojo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add directory structure explainer #66

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion docs/packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ author: mattwojo
ms.author: mattwoj
manager: jken
ms.topic: article
ms.date: 05/07/2025
ms.date: 10/01/2025
---

# Linux Software Repository for Microsoft Products
Expand All @@ -24,6 +24,22 @@ The Linux Software Repository can be configured to automatically install the Lin
> Optionally, if you prefer manual configuration, the Linux Software Repository configuration files are available at [https://packages.microsoft.com/config](https://packages.microsoft.com/config/). The name and location of these files can be located using the following URI naming convention:
`https://packages.microsoft.com/config/<Distribution>/<Version>/prod.(repo|list)`

### Directory structure

At the root of packages.microsoft.com, you’ll see folders like:

- `/config/<distro>/<version>/prod.list`: Contains repo configuration files for each supported distribution.
Copy link

@sdherr sdherr Oct 2, 2025

Choose a reason for hiding this comment

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

  • /config/<distro>/<version>/packages-microsoft-prod.[rpm|deb]: Provides the .list or .repo file to enable the distribution-specific repository for each system, as well as the appropriate signing key. If more a manual or non-default (for example, enabling the early-access not-yet-production "insiders" repos) approach is desired then individual .list or .repo files are available in this directory.

- `/repos/`: Contains product-specific repositories (for example, edge, azure-cli, microsoft-prod).
Copy link
Contributor

@daviddavis daviddavis Oct 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Technically, /repos/ contains all the apt repos including ones that aren't product specific. Like there's https://packages.microsoft.com/repos/microsoft-ubuntu-noble-prod/ which is also available at https://packages.microsoft.com/ubuntu/24.04/prod/.

But /repos/ is indeed the only way to access product-specific apt repos so I think this statement is fine as long as you point out that it's only for apt repos.

I'd also recommend adding an item here to say there's also /yumrepos/ for yum repos.

Copy link

@sdherr sdherr Oct 2, 2025

Choose a reason for hiding this comment

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

  • /repos/: Contains all .deb-based repos, including product-specific repos that are designed to work with all deb-based distributions, like edge or azure-cli. See individual product documentation for the preferred installation instructions.
  • /yumrepos/: Contains all .rpm-based repos, including product-specific repos that are designed to work with all rpm-based distributions, like edge or azure-cli. See individual product documentation for the preferred installation instructions.

- `/ubuntu/`: Contains distribution-specific repos for Microsoft packages that integrate with Ubuntu’s APT system.
Copy link
Contributor

@daviddavis daviddavis Oct 2, 2025

Choose a reason for hiding this comment

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

Maybe changing this to:

/<distro>/ (e.g. /ubuntu/): Contains distribution-specific repos for Microsoft packages

Copy link

@sdherr sdherr Oct 2, 2025

Choose a reason for hiding this comment

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

  • /<distro>/<version>/: Contains distribution-specific repos for Microsoft packages that are built for a particular distribution-version. These are all symlinks / copies of some repositories that can also be found under /repos/ or /yumrepos/, but surfaced at the top level too for convenience.


A few things to keep in mind regarding the packages.microsoft.com repo structure:

- The packages.microsoft.com repository is public and designed for programmatic consumption by package managers, not for manual browsing, though directory listing is enabled for convenience.
- The repos tree is product-centric, not distribution-centric. For example: `repos/edge/`, `repos/azure-cli/`, repos/microsoft-prod/', etc. Each contains metadata for multiple distributions, so the same product repo can serve Ubuntu, Debian, etc.
Copy link

@sdherr sdherr Oct 2, 2025

Choose a reason for hiding this comment

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

  • Some repos are product-centric, not distribution-centric. ... See individual product documentation for the preferred installation instructions.

- This differs from Ubuntu’s pool/main structure, which is strictly tied to Debian policy and archive layout.Ubuntu’s main pool is controlled by Canonical and only includes open-source or vetted packages, so proprietary software, such as Microsoft Edge, cannot be included there. This separation ensures Microsoft is able to directly provide updates and signing keys, as well as compliance with licensing (Microsoft Edge is closed-source). It also enables faster delivery of new versions without waiting for Ubuntu’s release cycle.
- Microsoft uses a centralized model rather than duplicating packages under each `distro` folder. This avoids redundancy and simplifies publishing across multiple Linux distributions.
Copy link
Contributor

@daviddavis daviddavis Oct 2, 2025

Choose a reason for hiding this comment

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

I'm not totally sure I understand what this means? Teams at Microsoft can and do publish different packages for different distros and distro versions.

Copy link
Contributor

@daviddavis daviddavis Oct 2, 2025

Choose a reason for hiding this comment

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

I guess this is maybe meant to refer to repos under /repos/ and /yumrepos/?

Copy link

@sdherr sdherr Oct 2, 2025

Choose a reason for hiding this comment

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

Drop.

- When you install the Microsoft repo config (packages-microsoft-prod.deb), it adds the correct deb `[arch=amd64] https://packages.microsoft.com/repos/edge` stable main line for your Linux distribution. APT then uses Microsoft’s metadata (Release, Packages.gz) to resolve dependencies. The actual `.deb` files live under `repos/edge/pool/main/...`, but you should never hardcode those paths because the APT package manager handles it.
Copy link
Contributor

@daviddavis daviddavis Oct 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Instead of saying that the repo config packages adds a line..., I would just say that the deb package adds a .list file to /etc/apt/sources.list.d/ for the repository.

Also, a couple things here that might be worth mentioning:

  • For yum repos, we provide packages-microsoft-prod.rpm packages similar to packages-microsoft-prod.deb
  • Each repo config package provides the repo signing key

Copy link
Contributor

@daviddavis daviddavis Oct 2, 2025

Choose a reason for hiding this comment

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

For yum repos, the .list file equivalent would be a .repo file. You can a few here:

https://packages.microsoft.com/config/rhel/10/

Copy link

@sdherr sdherr Oct 2, 2025

Choose a reason for hiding this comment

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

edge is a poor choice of repo to use as an example here, because we actually don't have a .deb that installs the edge repo. Maybe use the ubuntu repo as an example instead.


### Examples of available Microsoft products in the Linux Repository

The following Microsoft products are a few examples that offer Linux versions supported for install using the Linux Repository (package.microsoft.com). See the associated documentation link for more specific installation steps.
Expand Down