# nix-matrix-pkgs

[![Update Pins](https://guardianproject.dev/ops/nix-matrix-pkgs/badges/workflows/update.yml/badge.svg)](https://guardianproject.dev/ops/nix-matrix-pkgs/actions)

Pinned Nix packages for the Matrix ecosystem, providing multiple versions simultaneously so sites can upgrade independently.

Canonical Repository: https://guardianproject.dev/ops/nix-matrix-pkgs

## Overview

When running multiple Matrix deployments, each site needs to control exactly when it upgrades. Bumping a shared nixpkgs input upgrades every site at once, which is unacceptable for production services that require coordinated, intentional upgrades.

This repository maintains one standalone Nix flake per package version, each pinning nixpkgs to the revision where that version was current. A site picks a version by referencing the corresponding flake. Upgrading is an explicit change to the flake input, nothing more.

Currently tracked packages:

- matrix-synapse

The set of available versions is controlled by `rules.nix`, which declares how many recent versions to keep and any extra versions to pin per package. A CI workflow runs daily and on changes to `rules.nix`, automatically discovering new releases from nixpkgs-unstable and creating or removing version directories as needed.

## Usage

Reference a specific version directory as a flake input using `?dir=`:

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

    matrix-synapse-pinned.url = "git+https://guardianproject.dev/ops/nix-matrix-pkgs?dir=matrix-synapse@1.146.0";
    matrix-synapse-pinned.inputs.nixpkgs.follows = "";
  };

  outputs = { nixpkgs, matrix-synapse-pinned, ... }: {
    # Use the package directly
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        {
          nixpkgs.overlays = [ matrix-synapse-pinned.overlays.default ];
        }
      ];
    };
  };
}
```

Each version flake exposes:

- `packages.<system>.default` / `packages.<system>.matrix-synapse` -- the wrapped package
- `packages.<system>.matrix-synapse-unwrapped` -- the unwrapped package
- `overlays.default` -- overlay providing both `matrix-synapse` and `matrix-synapse-unwrapped`

To upgrade a site, change the `dir=` parameter to the new version and run `nix flake lock --update-input matrix-synapse-pinned`.

## Maintenance

This provider is actively maintained by [Guardian Project](https://guardianproject.info).

### Issues

For bug reports and feature requests, please use the [Issues][issues] page.

### Security

For security-related issues, please contact us through our [security policy][sec].

[issues]: https://guardianproject.dev/ops/nix-matrix-pkgs/issues
[sec]: https://guardianproject.info/contact/

## License

Copyright (c) 2026 Abel Luck <abel@guardianproject.info>

This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.