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 dependecy 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 miscategorize 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.

Back to top

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.

Back to top

Prerequisites

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

Back to top

Installation

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

  1. 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.

  2. 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.

  3. 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.

Back to top

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 accomodate you.

Back to top

How Greenkeeper works, step by step

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

  1. Greenkeeper watches your dependencies for updates

    Greenkeeper will watch npm’s changes feed for any update to any dependency in your package.json, except for those you’ve explicitly disabled.

  2. A dependency updates occurs

    Greenkeeper will open a branch that includes a single change: bumping that dependency’s version number in your package.json. 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.

  3. Greenkeeper verifies any pull requests

    To prevent malicious users from posing as 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!
Back to top

Resetting a repository

Sometimes, the Initital 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:

  1. If it exists, delete the greenkeeper/initial branch on the repo.

  2. Remove the repo from the Greenkeeper integration in the app installation settings on GitHub and save. You can find a link to those settings in the Account Dashboard, at the bottom of the corresponding account’s repository list. The link is unique for every GitHub account, so we can’t link to it here. This is the same place you do the second Greenkeeper setup step.

  3. On the same page, add the repo again, and save.

We’re working on making this more convenient by allowing you to reset repositories in the Account Dashboard.

If you are working in an organization that has whitelisted all repositories, you will probably not want to touch these settings, or may not be allowed to. In this case, please let us know which repo got stuck and we’ll sort it out for you.

Back to top

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.

Back to top

Enabling private scoped packages

Private scoped 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.

Back to top

Using Greenkeeper with lockfiles

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

Back to top

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 the 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" ] } }

Back to top