Mic92 / nixpkgs-review

nixpkgs-review Review pull-requests on https://github.com/NixOS/nixpkgs. nixpkgs-review automatically builds packages changed in the pull requests. Features • ofborg support: reuses evaluation output of CI to skip local evaluation, but also falls back if ofborg is not finished • provides a with all packages that did not fail to build • remote builder support • allows to build a subset of packages (great for mass-rebuilds) • allow to build nixos tests • markdown reports • GitHub integration: • post PR comments with results • approve or merge PRs (the last one requires maintainer permission) • show PR comments/reviews • logs per built or failed package • symlinks built packages to result directory for inspection Installation is included in nixpkgs. To use it without installing it, use: To run it from the git repository: Development Environment For IDEs: or just use: Usage First, change to your local nixpkgs repository directory, i.e.: If you've shallow cloned nixpkgs ( ), may be unable to perform merges due to missing merge base commits. Reclone nixpkgs without the flag. Note that your local checkout git will not be affected by , since it will use git-worktree to perform fast checkouts. Then run by providing the pull request number… …or the full pull request URL: The output will then look as follows: To review a local commit without pull request, use the following command: Instead of a commit or branch can also be given. To review uncommitted changes, use the following command: Staged changes can be reviewed like this: If you'd like to post the results as a formatted PR comment, pass the flag: If you'd like to exclude log snippets for failed builds, add the flag: Instead of posting a PR comment, nixpkgs-review can also print the report to the terminal using the flag. This flag will work for the and command.. Often, after reviewing a diff on a pull request, you may want to say "This diff looks good to me, approve/merge it provided that there are no package build failures". To do so, run the following subcommands from within the nix-shell provided by nixpkgs-review. Optional tools can integrate with several optional tools to enhance the user experience: nix-output-monitor (nom) will by default use nix-output-monitor if found in . This provides a more user-friendly build output with progress tracking and cleaner formatting. If you have installed but don't want to use it, you can pass to to use instead of . glow When glow is installed and available in , will use it to render markdown content (such as PR descriptions) with syntax highlighting and formatting in the terminal. delta When delta is installed and available in , will use it to display git diffs with enhanced visualization, including side-by-side comparisons and syntax highlighting. Some pull requests may require configuration for nixpkgs to test out. You can use the flag to supply extra configuration for nixpkgs. Using nixpkgs-review in scripts or other programs After building, will normally start a with the packages built, to allow for interactive testing. To use non-interactively in scripts, use the command, which can allow for batch processing of multiple reviews or use in scripts/bots. Example testing multiple unrelated PRs and posting the build results as PR comments for later review: also accepts a flag that allows to run a custom command inside the nix-shell instead of an interactive session: Review multiple pull requests at once nixpkgs-review accept multiple pull request numbers at once: This will first evaluate & build all pull requests in serial. Then a nix-shell will be opened for each of them after the previous shell has been closed. Tip: Since it's hard to keep track of the numbers, for each opened shell the corresponding pull request URL is shown. Remote builder Nixpkgs-review will pass all arguments given in to : As an alternative, one can also specify remote builder as usual in or via the nixos options in . This allows to parallelize builds across multiple machines. GitHub API token **Nixpkgs-review** requires a GitHub token to use cached evaluation results from GitHub and for certain commands (e.g., or ). Even for read-only operations, GitHub returns 403 error messages if your IP exceeds the rate limit for unauthenticated requests. **Automatic Token Usage** Nixpkgs-review will automatically use a GitHub token generated by gh (if installed). To set this up, run once to log in. **Manual Token Creation** If you prefer to create a token manually, generate a "Personal Access Token (Classic)" through GitHub's website. Refer to GitHub's documentation for detailed instructions. For posting generated reports, ensure the token is granted the scope. **Supplying the Token** You can provide your token to Nixpkgs-review using either the / environment variable or the parameter of the subcommand. Examples: Checkout strategy (recommend for r-ryantm + cachix) By default, will merge the pull request into the pull request's target branch (most commonly master). However, at times mass-rebuilding commits have been applied in the target branch, but not yet built by hydra. Often those are not relevant for the current review, but will significantly increase the local build time. For this case, the option can be specified to override the default behavior ( ). By setting its value to , will checkout the user's pull request branch without merging it: Only building a subset of packages To build only certain packages, use the (or ) flag. There is also the option that takes a regular expression to match against the attribute name. To skip building certain packages, use the (or ) flag. There is also the option that takes a regular expression to match against the attribute name. Unlike the option, a full match is required, which means you probably want to work with or . , , and can be used together, in which case the matching packages will be merged. Full documentation for regex…