A GitHub Action that creates meaningful pull requests with updates to your niv-managed dependencies, so you don't have to do menial chores.
BSD-3-CLAUSE License
= niv-updater: Automated dependency updates with niv
image:https://github.com/knl/niv-updater-action/actions/workflows/main.yml/badge.svg[CI] image:https://img.shields.io/github/v/release/knl/niv-updater-action[GitHub release (latest by date)]
This action will open a pull request to master
branch (or otherwise specified
branch) whenever https://github.com/nmattia/niv[niv] detects updates to
nix/sources.json
in your repository, for each dependency separately. Each PR
will contain a beautiful Changelog of all the changes in the update, like this:
image:./assets/niv-update-action-changelog.png[title="Changelog generated by niv-updater-action]
The best way to use niv-updater-action
is to set up a scheduled workflow. This
way, whenever there are new updates, you will get a PR that you can just
approve and avoid a lot of manual work.
== Example
Here is an minimal example of what to put in your
+.github/workflows/niv-updates.yml+
file to trigger the action.
== Configuration
=== Inputs
niv-updater-action
is configured using the following inputs:
pull_request_base
: (Optional) The name of the branch to issue the pull requestnix/sources.json
issources_file
: (Optional) The path in the repo to the sources.json
file.--sources-file
option. Defaults tonix/sources.json
.niv_version
: (Optional) The niv version to be used. Defaults to master
,niv-updater-action
will take the latest niv for each run. You may want*from-nixpkgs*
.branch_prefix
: (Optional) The prefix used for update branches, created byupdate/
.keep_updating
: (Optional) If PR already exists, keep it updated with newfalse
to maintain the old behaviour.skip_versioned_revisions
: (Optional, a boolean) If true
, will cause therev=v1.0.0
, niv would normally update it to the latest head of the branch,rev
holding the appropriate SHA. This is something one would nottrue
.skip_ssh_repos
: (Optional, a boolean) If true
, will cause the action tofalse
.whitelist
: (Optional) A list of dependencies, comma separated, that will beniv
.blacklist
: (Optional) A list of dependencies, comma separated, to skip fromlabels
: (Optional) A list of labels, newline separated, to apply to all|
block), as GitHub allowsshow_merges
: (Optional, a boolean) If true
, the changelog will containfalse
.message_prefix
: (Optional) The text that will be put in front of themessage_suffix
: (Optional) The text that will be put in after the generatedtitle_prefix
: (Optional) The text that will be put in front of thegithub_changelog_no_backreferences
: (Optional, a boolean) If true
, thetrue
.debug_output
: (Optional, a boolean) If true
, set -x
will be turned onfalse
.As the above list suggests, niv-updater-action
is highly configurable.
The following example exposes some of the knobs, many with their default values:
name: Automated niv-managed dependency updates
on:
schedule:
# * is a special character in YAML so you have to quote this string
# run this every day at 4:00am
- cron: '0 4 * * *'
jobs:
niv-updater:
name: 'Create PRs for niv-managed dependencies'
runs-on: ubuntu-latest
steps:
# notice there is no checkout step
- name: niv-updater-action
uses: knl/niv-updater-action@v13
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
# NOTE: All inputs are optional. This list them with their default values.
# Use the default branch for the repository
pull_request_base: ''
# The path in the repo to the sources.json file
sources_file: 'nix/sources.json'
# The niv version to use. master
will track the latest niv.
niv_version: 'master'
# Keep the PR updated with new changes
keep_updating: true
# The prefix to add to every created branch
branch_prefix: 'update/'
# Update all dependencies tracked by niv. Another example: 'common,jq,hub'
whitelist: ''
# Do not blacklist any of the dependencies. Another example: 'nixpkgs,niv'
blacklist: ''
# Note that | is really important for the labels
labels: |
documentation
good first issue
# Have some prefix and a suffix. Use '|' to keep newlines
message_prefix: |
## Motivation
Dependencies should be up to date.
message_suffix:
Notify @myorg/myteam.
# Have a prefix to the commit title itself, for example, to support conventional commits.
title_prefix: refactor:
== Secrets
Secrets are similar to inputs except that they are encrypted and only used by GitHub Actions. It's a convenient way to keep sensitive data out of the GitHub Actions workflow YAML file.
GITHUB_TOKEN
- (Required) The GitHub API token used to create pull requestsniv
.== Self hosted runner
Self-hosted runners are running with dynamic users so nix profile is not
accessible, as well as nix-env. As this action relies on nix-env to install
niv, the default configuration will not work. Thus, to use niv from available
nixpkgs, set niv_version
to pass:[*from-nixpkgs*]
. It will install niv
using nixpkgs
with nix-shell instead of nix-env.
To avoid using sudo
(also unavailable on self-hosted runners), the input
pass:[skip_ssh_repos]
should be set to true
.
Example: