{"id":14967901,"url":"https://github.com/nikstur/lon","last_synced_at":"2025-10-25T21:32:07.387Z","repository":{"id":255390543,"uuid":"840427478","full_name":"nikstur/lon","owner":"nikstur","description":"Lock \u0026 update Nix dependencies","archived":false,"fork":false,"pushed_at":"2024-09-05T18:42:41.000Z","size":30,"stargazers_count":13,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-31T10:51:13.132Z","etag":null,"topics":["nix","package-manager","updates","versioning"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikstur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-09T17:21:27.000Z","updated_at":"2024-12-15T09:00:47.000Z","dependencies_parsed_at":"2024-09-27T09:01:00.073Z","dependency_job_id":"3aa006dc-c4be-4059-9448-d52546d4680a","html_url":"https://github.com/nikstur/lon","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"a8b4406e5151af87b989564d4aa98ecd6d4d3500"},"previous_names":["nikstur/lon"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikstur%2Flon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikstur%2Flon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikstur%2Flon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikstur%2Flon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikstur","download_url":"https://codeload.github.com/nikstur/lon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238212446,"owners_count":19434955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nix","package-manager","updates","versioning"],"created_at":"2024-09-24T13:38:50.739Z","updated_at":"2025-10-25T21:32:07.382Z","avatar_url":"https://github.com/nikstur.png","language":"Rust","funding_links":[],"categories":["package-manager","Command-Line Tools"],"sub_categories":[],"readme":"# Lon\n\nLock \u0026 update Nix dependencies.\n\n## Features\n\n- Only uses SRI hashes\n- Supports fixed outputs of `builtins.fetchGit` by using an SRI hash and thus\n  enables caching for these sources in the Nix Store\n- Allows overriding dependencies via an environment variable for local\n  development\n- Leverages modern Nix features (concretely this means Nix \u003e= 2.4 is required)\n- Built-in bot to automate dependency updates for GitHub, GitLab, and Forgejo\n- Supports the [Lockable HTTP Tarball Protocol](https://nix.dev/manual/nix/latest/protocols/tarball-fetcher)\n\n## Installation\n\nThe easiest way to use Lon is directly from Nixpkgs. It is currently available\nin the `nixos-unstable` branch and will be included in NixOS releases starting\nfrom 25.05.\n\nYou can also invoke it via `nix run github:nikstur/lon`.\n\n```console\n$ lon\nUsage: lon [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  init      Initialize lon.{nix,lock}\n  add       Add a new source\n  update    Update an existing source to the newest revision\n  modify    Modify an existing source\n  remove    Remove an existing source\n  freeze    Freeze an existing source\n  unfreeze  Unfreeze an existing source\n  bot       Bot that opens PRs for updates\n  help      Print this message or the help of the given subcommand(s)\n\nOptions:\n  -q, --quiet                  Silence all output\n  -v, --verbose...             Verbose mode (-v, -vv, etc.)\n  -d, --directory \u003cDIRECTORY\u003e  The directory containing lon.{nix,lock}\n  -h, --help                   Print help\n  -V, --version                Print version\n```\n\n## Usage\n\nInitialize Lon:\n\n```console\n$ lon init\nWriting lon.nix...\nWriting empty lon.lock...\n```\n\nInitialize from an existing Niv lock file:\n\n```console\n$ lon init --from niv --source nix/sources.json\nWriting lon.nix...\nInitializing lon.lock from \"nix/sources.json\"\nConverting bombon...\nLocked revision: 2c7df3b0877337b9ce4825ffbaa6e5148b96acb4\nLocked hash: sha256-EiV+QA0RZqzt+lrYdsao7p1LhHB+fICjT4do4L+lIdM=\nConverting nixpkgs...\nLocked revision: 292fa7d4f6519c074f0a50394dbbe69859bb6043\nLocked hash: sha256-GaOZntlJ6gPPbbkTLjbd8BMWaDYafhuuYRNrxCGnPJw=\n```\n\nAdd a new GitHub source:\n\n```console\n$ lon add github nixos/nixpkgs master\nAdding nixpkgs...\nLocked revision: 543931cdbf2b2313479c391d956edb5347362744\nLocked hash: sha256-8pTC0OIYD47alDVf2mwSytwARCwoH6IqnUfpyshyQX8=\n```\n\nAdd a new Git source:\n\n```console\n$ lon add git snix https://git.snix.dev/snix/snix.git canon\nAdding snix...\nLocked revision: e33040a3e1a500e73dd8a4c2b9e793d7cb85384f\nLocked hash: sha256-TpWEIhAgzGIupKARl+a3btrBaV9wQGYyxzN42Cnmu14=\nLocked lastModified: 1761157523\n```\n\nGit sources also support fetching submodules. Enable it by supplying\n`--submodules` to Lon.\n\nAdd a new [(Lockable)](https://nix.dev/manual/nix/latest/protocols/tarball-fetcher) Tarball source:\n\n```console\nAdding lix...\nLocked immutable URL: https://git.lix.systems/api/v1/repos/lix-project/lix/archive/18efc848fe7b79c84a2e4311ac9ce3492b7aaa82.tar.gz?rev=18efc848fe7b79c84a2e4311ac9ce3492b7aaa82\nLocked revision: 18efc848fe7b79c84a2e4311ac9ce3492b7aaa82\nLocked hash: sha256-B4TrQgd/3pm0SvnCkYkvLuldhrO+9QRB/mKa6JrItNo=\n```\n\nIf the provided URL doesn't point to a lockable tarball, it pins the provided\nURL directly. You can change the URL of a non-lockable tarball by calling\n`lon modify $name --url $new_url`.\n\nYou can now access these sources via `lon.nix`:\n\n```nix\nlet\n  sources = import ./lon.nix;\n  pkgs = import sources.nixpkgs { };\n  lix = import sources.lix;\nin\n  {\n    nix = pkgs.nix;\n    lix = lix.packages.x86_64-linux.default;\n  }\n```\n\nYou can update individual sources via `lon update nixpkgs` or all sources via\n`lon update`. You can even let Lon create a commit for the updates it performs\nvia `lon update --commit`. The commit message will list all the updates\nperformed similar to the way `nix flake update --commit-lock-file` does.\n\n### Overriding a Source for Local Development\n\nYou can use environment variables that follow the scheme `LON_OVERRIDE_${name}`\nto override a source for local development. Lon will use the path this variable\npoints to instead of the fetching the locked source from `lon.lock`.\n\nNote that no sanitizing of names is performed by Lon. That's why you should\ngive your sources names that only contain alphanumeric names.\n\n## Bot\n\nWith the subcommand `bot \u003cforge\u003e`, you can automatically update your sources. Lon\niterates over each source and if an update is available, performs it and opens\na PR.\n\nCurrently, GitLab (`gitlab`), GitHub (`github`) and Forgejo (`forgejo`) are supported.\n\n```console\nBot that opens PRs for updates\n\nUsage: lon bot \u003cCOMMAND\u003e\n\nCommands:\n  gitlab   Run the bot for GitLab\n  github   Run the bot for GitHub\n  forgejo  Run the bot for Forgejo\n  help     Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help  Print help\n```\n\n### GitLab Usage\n\n1. Create a [Project Access Token] with the role `Developer`, and the `api` and\n   `write_repository` scope. You can also create a [Group Access Token] so that\n   the entire group can use the bot.\n2. Store the token in a CI/CD variable called `PROJECT_ACCESS_TOKEN`.\n3. Configure a [Scheduled Pipeline].\n4. Extend your `.gitlab-ci.yml` with the following snippet. Make sure to set\n   `LON_PUSH_URL` including the token stored in `PROJECT_ACCESS_TOKEN`.\n\n```yml\nstages:\n  - update\n\nlon:\n  stage: update\n  rules:\n    # Only run on a schedule and only on the main branch.\n    - if: $CI_PIPELINE_SOURCE == \"schedule\" \u0026\u0026 $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH\n  variables:\n    LON_TOKEN: \"$PROJECT_ACCESS_TOKEN\"\n    LON_PUSH_URL: \"https://token:${LON_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git\"\n    LON_LABELS: \"bot,lon\"\n  script:\n    - lon bot gitlab\n```\n\n[Project Access Token]: https://docs.gitlab.com/user/project/settings/project_access_tokens/\n[Group Access Token]: https://docs.gitlab.com/user/group/settings/group_access_tokens/\n[Scheduled Pipeline]: https://docs.gitlab.com/ci/pipelines/schedules/\n\n### GitHub Usage\n\n1. [Allow GitHub Actions to create Pull\n   Requests](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests)\n2. Add a workflow for updates (e.g. `.github/workflows/update.yml`). Use the\n   following snippet to create a functioning workflow. Note specifically the\n   permissions and environment variables.\n\n```yml\njobs:\n  update:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n    steps:\n      - uses: actions/checkout@v4\n      - env:\n          LON_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          LON_LABELS: \"lon,bot\"\n        run: lon bot github\n```\n\n### Forgejo Usage\n\n#### Basic usage\n\nAdd a workflow for updates (e.g. `.forgejo/workflows/update.yml`). Use the\nfollowing snippet to create a functioning workflow.\n\n```yml\njobs:\n  update:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - env:\n          LON_TOKEN: ${{ secrets.FORGEJO_TOKEN }}\n          LON_LABELS: \"lon,bot\"\n        run: lon bot forgejo\n```\n\nNote, however, that the pull requests opened via this actions will not trigger workflows\ndue to how the [automatic token](https://forgejo.org/docs/latest/user/actions/#automatic-token) is designed.\n\n#### With an Access Token\n\nTo alleviate the previous problem, it is possible to create a personal access token to\nuse instead of the automatic one.\n\n1. Create an [Access Token] with the `write:repository` scope\n2. Add the token to the actions secret variables\n\nThe next snippet creates such a workflow.\n\n```yml\njobs:\n  update:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          token: ${{ secrets.ACCESS_TOKEN }}\n      - env:\n          LON_TOKEN: ${{ secrets.ACCESS_TOKEN }}\n          LON_LABELS: \"lon,bot\"\n        run: lon bot forgejo\n```\n\n[Access Token]: https://docs.codeberg.org/advanced/access-token/\n\n### Config\n\nThe bot is configured exclusively via environment variables.\n\n#### Required\n\n- `LON_TOKEN`: The token to access the forge API and push to the repository.\n\n#### Optional\n\n- `LON_USER_NAME`: The Git user name under which the changes are made.\n- `LON_USER_EMAIL`: The Git user email under which the changes are made.\n- `LON_LABELS`: The labels to set on the Pull Request as a comma separated\n  string (e.g. `\"lon,bot\"`).\n- `LON_PUSH_URL`: The URL to use to push to the repository. This can be used to\n  set a token in the URL. For GitLab, this is required.\n- `LON_LIST_COMMITS`: The number of commits to list in the commit message that\n  occurred between the old revision and the updated revision. If this is unset,\n  none are listed.\n\n#### GitLab Specific (Required)\n\nThese are [predefined in GitLab\nCI/CD](https://docs.gitlab.com/ci/variables/predefined_variables/#predefined-variables).\n\n- `CI_API_V4_URL`\n- `CI_PROJECT_ID`\n- `CI_DEFAULT_BRANCH`\n\n#### GitHub Specific (Required)\n\nThese are [predefined in GitHub\nActions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables).\n\n- `GITHUB_REPOSITORY`\n\n## Contributing\n\nContributions are welcome!\n\n### Tests\n\nLon has a growing test suite that consists of two parts:\n\n- normal Rust unit/integration tests\n- VM tests\n\nThe VM tests are also written in Rust but are ignored when you call `cargo\ntest`. They are designed to only run inside a VM because they access resources\nmocked by another VM. You can call these VM tests via `nix build\n.#checks.x86_64-linux.lon`.\n\nYou can add another VM test by creating one in inside the `ignored` module of\nthe Rust integration tests.\n\nAll the tests are included in the flake checks. You can run all of them via\n`nix flake check`.\n\n### Invariants\n\n- Support only few repository hosters: Lon does not aim to support all possible\n  repository hosters. It will focus on the most important ones and will as much\n  as possible rely on generic protocols (e.g. Git) to find and lock updates.\n  GitHub is already an exception to this rule, but because of its ubiquity and\n  importance, it is unavoidable.\n- No tracking besides Git branches. You can still lock e.g. a specific\n  revision, but you will have to update it manually.\n\n## On the Shoulders of Giants\n\nLon is heavily inspired by [niv](https://github.com/nmattia/niv) and\n[npins](https://github.com/andir/npins) and builds on their success.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikstur%2Flon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikstur%2Flon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikstur%2Flon/lists"}