Documentation

First off: welcome, and thanks for trying Greenkeeper! If you can’t find what you’re looking for here, there’s also the FAQ page, and if that doesn’t help, you can contact us directly.

Documentation overview

What Greenkeeper does, and why

In short, Greenkeeper makes sure that you know when your project’s dependency updates break your code.

Greenkeeper sits between npm and GitHub, observing all of the modules your repository depends on. Each time one of them is updated, Greenkeeper opens a new branch with that update. The repository’s CI tests kick in, and Greenkeeper watches them to see whether they pass or not.

Based on the test results and your current version definitions Greenkeeper will open up clear, actionable issues for you. If an update doesn’t break your code, nothing will happen, because everything is fine and no human intervention is required. If things do break, you’ll be informed immediately: you’ll know exactly which update to which dependency caused the problem, and you’ll be nicely set up to fix the problem.

Doesn’t semver take care of this? Not reliably, no. Versioning decisions are still often made by humans, and humans often version irrationally. Humans are also fallible, and sometimes mis-categorize a commit. Somebody else's chore may break your code, because you’re using theirs in a way they haven’t forseen. The only way to be sure is to run your tests on each and every update. And if Greenkeeper weren’t around, this would be extremely tedious, which is why basically nobody makes the effort to continually stay up to date.

Differences between plans

Using Greenkeeper on public repositories is free. If you intend to have it run on private repositories, you’ll need to add your payment details on in the Greenkeeper Account Dashboard.

Pricing varies depending on the type of GitHub account Greenkeeper is installed on, and how many repositories it’s enabled for.

Prerequisites

Greenkeeper has a number of requirements for each repository it is meant to watch:

The repo must have at least one package.json file somewhere in the project
The repo must have a form of Continuous Integration (CI) that sets commit statuses on branches (like CircleCI, CodeShip or Travis CI, for example, but other services work too)
The CI must be active on the repo and be allowed to act on new branches
Issues must be enabled for the repo (careful: issues are disabled by default on forked repositories)
If you do not have a paid subscription, the repo must be public

Installation

Setting up Greenkeeper to watch one of your repositories requires three steps:

Install Greenkeeper
Install the Greenkeeper GitHub app on the repository’s parent organization or user account (you’ll only need to do this once per account).

To install, visit Greenkeeper’s app page on GitHub and click Install. If you’ve already installed it somewhere, click on Configure instead. You can then choose which organization or account to install the app in.
Grant repository access
Now set up the Greenkeeper app and tell it which of the account’s repositories to try and watch.

Find Greenkeeper’s settings page (this is a different URL for every account, so we can’t link to it, sorry). It’s in your organization or account settings under Installed GitHub Apps. Select Greenkeeper, and scroll all the way down to the section titled Repository access. Here, choose Only select repositories (we really don’t recommend All repositories) and add one or more repositories you want Greenkeeper to watch.

The GitHub interface that lets you add and remove repository access for Greenkeeper

You can also find a link to these settings in the Account Dashboard, at the bottom of the corresponding account’s repository list.
Enable Greenkeeper on each repo
Enable Greenkeeper on that individual repository by merging the Initial Pull Request.

To set itself up on a repository, Greenkeeper will open an Initial Pull Request. This will attempt to update all dependencies at once, so you’re up to date. In addition, it will add the Greenkeeper badge to your project’s readme.md. Note that Greenkeeper will only be able to do this if your repository meets all the prerequisites.

Important: Greenkeeper will only start watching the repository’s dependencies after this pull request has been merged. It will also remind you after a few days in case you forget.

Also Important: The initial PR will not be opened if all dependencies are already up to date, and the readme.md already has a badge. In this case, Greenkeeper is silently enabled.

You can check the status of each repository in the Greenkeeper Account Dashboard.

The Initial Pull Request may take a while to appear, depending on how busy GitHub and your CI service are, and how complex your tests are. See checking repository states for details on managing Greenkeeper across multiple GitHub accounts and repositories, and find out how to reset a repository when things go wrong.

Checking repository states

The Account Dashboard shows you each repository’s state, indicating where Greenkeeper is installed and/or enabled. Note that this list can only show repositories you’ve granted Greenkeeper access to.

The repository list in the Greenkeeper Account Dashboard

A repo is marked red if the Initial Pull Request doesn’t exist (yet). This could be because one or more of the prerequisites isn’t met, because your CI is still running and the Initial Pull Request simply isn’t ready yet, or occasionally, because some information got lost between your CI service, GitHub and Greenkeeper. If you’re sure all prerequisites are fulfilled and your CI completed its run on the Greenkeeper branch, but no Initial Pull Request appeared, you can try resetting the offending repo.

It is however entirely possible that you’re using npm in a way we’ve never seen before, or have your CI configured in an interesting way, or some other aspect of your setup works in a way that’s new to Greenkeeper. If you suspect this may be the case, we’d be very grateful if you could let us know, and we’ll try to accommodate you.

How Greenkeeper works, step by step

This section covers how Greenkeeper works after the three installation steps above have been completed

Greenkeeper watches your dependencies for updates
Greenkeeper will watch npm’s changes feed for any update to any dependency in your package.json files, except for those you’ve explicitly ignored.
A dependency update occurs
Greenkeeper will open a branch that bumps that dependency’s version number in your package.json files. Your CI tests will run on that branch, and once they complete, one of three things will happen:
1. It’s an in-range update, and your tests pass:
  Greenkeeper deletes the branch and stays silent, because everything still works!
  
  In-range means: If you specify a range of ^1.0.0, and 1.0.1 is released, that update is in-range. Users of your package would receive this update when they run npm install. Consult npm’s semver calculator to see which updates apply to your specified ranges, per package.
2. It’s an in-range update, and your tests fail:
  Greenkeeper will notify you about that breakage by opening up an issue, and it will also let you know whether pinning the dependency to the previous version will fix the build. In addition, Greenkeeper will keep checking if any new version of that dependency fixes this version’s breakage, and will also notify you about that in the issue thread.
  
  An example of an issue triggered by a breaking in-range update
3. It’s an out-of-range update:
  Greenkeeper opens a pull request, and your CI runs there. Your users would never encounter this version because it’s out of range, but if the update contains changes you want (security fixes, performance improvements, better compatibility etc.), this pull request is a good basis for work in that regard. Plus, if you trust your tests and they all pass, you could merge the pull request straight away.
  
  An example of a pull request triggered by an out-of-range update
  
  You’ll only get one pull request per dependency, if additional updates come in, Greenkeeper will update that pull request with the new dependency version (triggering your CI), and add a comment to let you know about the update.
  
  A follow-up update for an out-of-range update will appear as an update to the original pull request
  
  Out-of-range means: If you specify a range of ^1.0.0, and 2.0.0 is released, that update is out-of-range. Users of your package will never encounter this update unless you bump the dependency’s version number and release your package again. Consult npm’s semver calculator to see which updates apply to your specified ranges, per package.
Greenkeeper verifies any pull requests
To prevent malicious users from impersonating the Greenkeeper bot, Greenkeeper will attach a status check from greenkeeper/verify to each pull request it opens. If this is missing, the pull request is probably not from us, and you should treat it with caution. It looks like this:

Only a pull request with a greenkeeper/verify status check is genuine. Don’t accept any fakes!

Note that this status should not be set to required in your GitHub repo settings, since that requirement will apply to all pull requests, not only those opened by Greenkeeper. Since Greenkeeper doesn’t verify non-Greenkeeper PRs, the greenkeeper/verify status will never be reported, and your PRs will be stuck on Some checks haven’t completed yet forever.

Resetting a repository

Sometimes, the Initial Pull Request will never be opened. This can have many reasons: you may have forgotten to allow your CI to work on Greenkeeper branches, or issues may be disabled on the target repo, the CI service may have timed out… in any case, you may want to start over. Here’s how:

Click the 'fix repo' button on https://account.greenkeeper.io

Here is what the reset does to your repository:

deletes all branches and issues that Greenkeeper created.
creates a new initial Greenkeeper branch & pull request

Please note that the reset process can take up to 30 minutes until you see a new initial branch on your repository. If you still didn't get a branch after that time please let us know which repo got stuck and we’ll sort it out for you.

Pinning a dependency

Pinning a dependency is a legitimate option when you don’t have the time or resources to fix a problem introduced by a dependency update. Greenkeeper will let you know whether pinning to the dependency’s previous version (downgrading) would solve the new issue, and will then give you that option in the issue thread.

When a dependency update breaks your build, Greenkeeper lets you pin (downgrade) the last working version right there in the GitHub issue.

Once you’ve pinned a package, every subsequent update to it will be considered out-of-range by Greenkeeper.

Enabling private packages

Greenkeeper has native support for private packages in npm and GitHub. Private packages require an extra setup step that is detailed in each Initial Pull Request. It involves URLs and tokens that are unique to each account and repository, and which are only created when each Initial Pull Request is generated. Please consult your repository’s Initial Pull Request for instructions specific to that repository. For lockfile updates, the necessary access tokens can be added in the Greenkeeper Account Dashboard.

Using Greenkeeper with lockfiles

Greenkeeper has built-in support for npm and yarn lockfiles with public and/or private packages (package-lock.json and yarn.lock). These will be updated automatically whenever the corresponding package file changes. Lockfiles that include private packages will also be updated; the necessary access tokens can be added in the Greenkeeper Account Dashboard. We currently support private packages from npm and GitHub.

Greenkeeper supports shrinkwrap via an additional package called greenkeeper-lockfile. Please consult that package’s readme for details.

If you have greenkeeper-lockfile set up, this is how the different lockfiles are treated:

npm-shrinkwrap.json can be part of a release to npm and defines exactly which dependency versions your users get. If an update is covered by the defined range in your package.json, Greenkeeper does nothing if npm-shrinkwrap.json is present, since that guarantees that the new dependency will never be installed anyway. If there’s an out-of-range update, you get a Pull Request so you are aware of the update and can decide whether you’re interested in it.

package-lock.json and yarn.lock work differently, since these two are not published to npm and have no influence on which dependency versions your users get. For in-range updates, Greenkeeper will always open a branch so your CI can run and update these lockfiles. For out-of-range updates, you get a Pull Request, as usual.

If you do not want in-range branches for lockfiles, you can disable them in your package.json file:

// package.json
{
  …
  "greenkeeper": {
    "lockfiles": {
      "outOfRangeUpdatesOnly": true
    }
  }
}

When using private dependencies, you can configure read-only access tokens to both npm and GitHub in the Greenkeeper Account app.

Configuring access tokens for npm and GitHub.

Using Greenkeeper in a monorepo

Greenkeeper supports repos with multiple package.json files (monorepos). To make updating multiple files simpler and less noisy, they can be grouped, which means that they will all receive dependency updates, pull requests and issues from Greenkeeper together.

The Initial Pull Request will add a greenkeeper.json to your repo. This contains the group configuration; by default, all package.json files will be collected in a group called default. You can rename, add and remove groups and freely assign each package.json file to whichever group you like. It’s common, for example, to have one frontend group and one backend group, each with a couple of package.json files. In any case, all files in a group will have their updates collected into single PRs and issues. Here’s what that would look like:

// greenkeeper.json
{
  "groups": {
    "frontend": {
      "packages": [
        "admin-dashboard/package.json",
        "frontend/package.json"
      ]
    },
    "backend": {
      "packages": [
        "stats/package.json",
        "api-server/package.json"
      ],
      "ignore": ["hapi"]
    }
  },
  "ignore": ["standard"]
}

In this example, a repository’s package files are split into two groups, frontend and backend, and the files in each group will always be updated together. In addition, the backend group ignores the hapi dependency, and the entire repo ignores the standard dependency.

Important: If you have more than one package.json file, or your single package.json file is not in the root of the repo, Greenkeeper will only handle the package.json files you specify in greenkeeper.json. So if you want to ignore one, just omit it from all the packages arrays.

You can also ignore dependencies on group level by adding them to an array under an ignore key within each group object, see the backend group in the example above.

Greenkeeper will open an issue if you’ve accidentally changed greenkeeper.json in a way it doesn’t understand, and will try to explain where the problems are.

Using Greenkeeper with monorepo dependencies

Greenkeeper will group releases from some of the more popular monorepo dependencies together, at time of writing these are Angular, Babel, BaseT, Jest, PouchDB, React and Storybook.

You can view the release groups and also submit changes and additions to the monorepo release definitions module on GitHub.

Ignoring certain dependency’s updates

You may have good reasons for not wanting to update to a certain dependency right now. In this case, you can change the dependency’s version string in a package.json file back to whatever you prefer.

To make sure Greenkeeper doesn’t nag you again on the next update, add a greenkeeper.ignore field to your package.json, containing a list of dependencies you don’t want to update.

        // package.json
{
  …
  "greenkeeper": {
    "ignore": [
      "package-names",
      "you-want-me-to-ignore"
    ]
  }
}

You can also configure ignored dependencies in a separate greenkeeper.json file, see the monorepo documentation for details. Nested ignore configurations (config file, group config, individual package file) will all be applied, but we recommend keeping global, repository-wide ignores in the greenkeeper.json instead of a root package.json.

Setting up custom commit messages

You can customize all of Greenkeeper’s commit messages by adding a greenkeeper.commitMessages key to your package.json. This is useful if you’d like Greenkeeper to adhere to a specific message style, eg. some projects prefer a change to dev dependencies to be a "Chore", for others it’s a "Fix".

These are all the commit strings and the variables you can use within them. And yes, there’s emoji support!

        // package.json
{
  …
  "greenkeeper": {
    "commitMessages": {
      "initialBadge": ":memo: Docs: Add Greenkeeper badge",
      "initialDependencies": ":gem: Upgrade: Update dependencies",
      "initialBranches": ":tada: Build: Whitelist greenkeeper branches",
      "dependencyUpdate": ":gem: Upgrade: Update ${dependency} to version ${version}",
      "devDependencyUpdate": ":gem: Upgrade: Update ${dependency} to version ${version}",
      "dependencyPin": ":bug: Fix: Pin ${dependency} to ${oldVersion}",
      "devDependencyPin": ":bug: Fix: Pin ${dependency} to ${oldVersion}"
    }
  }
}

Setting up custom pull request titles

You can customize all of Greenkeeper’s pull request titles by adding a greenkeeper.prTitles key to your package.json.

        // package.json
{
  …
  "greenkeeper": {
    "prTitles": {
      "initialPR": "Update dependencies to enable Greenkeeper!!!",
      "initialPrBadge": "Add badge to enable Greenkeeper!!!!",
      "initialPrBadgeOnly": "Add Greenkeeper badge!!!",
      "initialSubgroupPR": "Update dependencies for ${group}!!!",
      "basicPR": "Update ${dependency} to the latest!!!",
      "groupPR": "Update ${dependency} in group ${group} to the latest!!!!"
    }
  }
}