Skip to content
This repository has been archived by the owner on Jul 12, 2022. It is now read-only.

Getting Started

Jump to bottom
Anthony Steele edited this page Feb 5, 2019 · 34 revisions

NuKeeper Logo

Getting Started With NuKeeper. A guide focused on examples, from simple on upwards.

Getting NuKeeper

You will first need .NET Core 2.1 or later installed.

NuKeeper can be found on NuGet as a global tool. The source is on GitHub.

Install NuKeeper with:

dotnet tool install nukeeper --global

Update NuKeeper with:

dotnet tool update nukeeper --global

Using NuKeeper

Running nukeeper with no arguments shows the help.

nukeeper --help

Help on a NuKeeper command

nukeeper repo --help

Using NuKeeper Inspect code

Use the inspect command to show updates that can be applied to a solution.

Inspect the current folder:

cd C:\code\MyApp
nukeeper inspect

This produces output e.g.

Found 2 package updates
Microsoft.Extensions.Configuration.Json to 2.1.0 from 2.0.2 in 1 place since 13 days ago.
Swashbuckle.AspNetCore to 2.5.0 from 2.4.0 in 1 place since 6 days ago.

You can inspect a different folder:

nukeeper inspect C:\code\MyApp

Update command

Use the update command to apply an update to code.

Apply a update chosen by NuKeeper to a solution:

cd C:\code\MyApp
nukeeper update

or

nukeeper update C:\code\MyApp

Apply up to ten package updates in a run:

nukeeper update C:\code\MyApp --maxpackageupdates 10

Apply an update to a particular package:

nukeeper update C:\code\MyApp --include SomePackageThatIWant

Exclude updates to a particular package:

nukeeper update C:\code\MyApp --exclude SomePackageThatIDoNotWant

Apply updates to all packages of the AWS SDK, a set of closely-related packages with names that all start with AWSSDK.:

nukeeper update C:\code\MyApp --include ^AWSSDK. --maxpackageupdates 100

Include and exclude

Include and exclude package names with --include and --exclude. e.g. --include nlog or --exclude aspnet

Exclude specifies that packages that match the pattern will not be applied. Include specifies that only packages that match the pattern can be applied.

The patterns are regular expressions. This is not a regular expression tutorial, but it is worth knowing a few common ways to use it:

  • By default, it is substring match. e.g. --include NLog will include all package names that contain the text NLog.
  • You can anchor the match with ^ at the start or $ at the end to ensure that the package name starts and/or ends with the specified text. Using both start and end anchors means that it must be an exact match for the whole package name. e.g. i=^NLog$ will include only the package NLog.
  • You can use | as an "or" to match one of several things. However since on the command line the | has special meaning to pipe command output, you have to escape it.
    • On the command line on windows you escape the | as ^|. e.g. to exclude updates to framework packages: --exclude (Microsoft^|System^|AspNet).
    • In the bash shell on linux, you instead escape by wrapping the whole argument in single quotes, e.g. --exclude '(Microsoft|System|AspNet)'.

Restricting updates

Restrict by version change

When I do not want major version changes, only minor or patch version changes.

nukeeper update --change minor

e.g. An update from version 1.2.3 to version 1.5.0 will be selected even if version 2.0.0 is also available. Semantic versioning calls these three numbers major, minor and patch versions. If semantic versioning is being well-used, then breaking changes only appear in major versions.

The default value is major.

Restrict by package age

When I am cautious, only want updates that have been available for 3 weeks or more.

nukeeper update --age 3w

You can specify minimum update age in weeks (w), days (d) or hours (h), e.g. --age 6w, or --age 12h. The default is 7 days. You can use zero (0) on it's own.

This is a precaution against being on the "bleeding edge" by taking new packages immediately. Sometimes issues are discovered just after package release, and the package is removed or replaced by a x.0.1 fix release.

When I am living on the edge, I will take updates as soon as they are available.

nukeeper update --age 0

Custom NuGet feeds

If you have a custom or private NuGet feed, it is recommended that you use a NuGet.config file in your repository. It will be used by NuKeeper, and by other tools. You can specify a list of NuGet sources on the command line. e.g.

nukeeper update --source https://api.nuget.org/v3/index.json --source http://packages.mycompany.com/nugetfeed

If you override this, you can chose to include the global public api.nuget.org feed or not. You may not need to, if your internal feed proxies the nuget.org feed.

The order of precedence is:

  1. sources on command line
  2. NuGet.config file
  3. Default public NuGet.org feed

Repository command

Github AzureDevOps BitBucket GitLab
✔️ ✔️ ✔️ ❌

Use the repository command to raise multiple pull requests against a GitHub repository. The repository does not need to be present on the file system beforehand. It will be fetched to a temporary folder.

If you run these command lines regularly, you can automatically get update pull requests like this one and always keep a project's dependencies up to date.

Raising a pull request is intended to hook into the automated tests and manual review process that you use. You can then choose to merge or reject the pull request based on the outcome.

In order to work with repositories, you will first need a personal access token.

Github

nukeeper repo https://github.com/myorg/myrepo token

Azure DevOps

nukeeper repo https://dev.azure.com/{org}/{project}/_git/{repo}/ token

The minimum scope of access associated for the token to make NuKeeper work is "Code (Read & write)".

With Arguments

I want one Pull Request that applies a top ten updates to my repository

nukeeper repo url token --maxpackageupdates 10 --consolidate

I want one Pull Request that applies updates to all packages of the AWS SDK:

nukeeper repo url token --maxpackageupdates 100 --include ^AWSSDK. --consolidate

Hidden token

The token is a secret; often you don't want to put it on the command line, e.g. if this command line is in a script stored in a public repository. In that case, you can put it in the appropriate environment variable blow and NuKeeper will automatically read it from there. NuKeeper_github_token Nukeeper_azure_devops_token

set NuKeeper_github_token=mygithubtoken

Custom GitHub API server

If you have a a different GitHub server, e.g. one hosted inside your organisation, you need to find out where its API root URL is. You can specify it to Nukeeper with e.g. --api=https://github.mycompany.com/api/v3. The default is the public API at https://api.github.com

The host must contain the word github to be able to select the right platform.

Options for controlling pull requests

NuKeeper often operates in a target-rich environment, where you don't want to raise all the potential pull requests at once.

NuKeeper sorts the pull requests, using heuristics so that more impactful updates are at the top, but you also can control how many pull requests are raised, when and what levels of change.

Examples

--maxpackageupdates 2 Limit to two pull requests generated by a run. The default value is 3.

--change minor Do not allow major version changes.

--age 10d Do not apply any version change until it has been available for 10 days. The default is 7 days. You can also specify this value in weeks with e.g. age=6w or hours with e.g. age=12h.

Organisation command

Github AzureDevOps BitBucket GitLab
✔️ ❌ ❌ ❌

Use the organisation command to raise multiple pull requests against multiple GitHub repositories within the same GitHub Organisation.

nukeeper org myteam mygithubtoken

Global command

Github AzureDevOps BitBucket GitLab
✔️ ❌ ❌ ❌

Use the global command to update a particular package across your entire github server.

nukeeper global mygithubtoken --include PackageToUpdate --api https://github.mycompany.com/api/v3

Output and debug logging

To make logging show more details.

nukeeper inspect C:\code\MyApp --verbosity detailed

Send debug logs to a file instead of console.

nukeeper inspect C:\code\MyApp --logfile somefile.log

To turn off logging entirely.

nukeeper inspect C:\code\MyApp --logdestination off

Code metrics as the only output

nukeeper inspect C:\code\MyApp --logdestination off --outputformat metrics

Report updates in Comma-separated value format, to file as output.

nukeeper inspect nukeeper inspect C:\code\MyApp --outputformat csv --outputfile packages.csv

Run Nukeeper on a remote repository, and just generate project metrics, no Pull Requests.

nukeeper repo https://github.com/myorg/myrepo mygithubtoken --maxpackageupdates 0 --logdestination off --outputformat metrics

Run NuKeeper on a remote repository without any logging or output at all, just Pull Requests generated

 nukeeper repo https://github.com/myorg/myrepo mygithubtoken --logdestination off --outputdestination off

For all possible options and modes, see Configuration

Clone this wiki locally