- What Greenkeeper does, and why
- Differences between plans
- Checking repository states
- How Greenkeeper works, step by step
- Resetting a repository
- Pinning a dependency
- Enabling private scoped packages
- Using Greenkeeper with lockfiles
- Ignoring certain dependency’s updates
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.
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
Greenkeeper has a number of requirements for each repository it is meant to watch:
- The repo must have a
package.jsonin the repo root
- The repo must have a form of Continuous Integration (CI) that sets commit statuses on branches (like 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)
- Greenkeeper doesn’t support multiple
package.jsonfiles per repo yet, but it does work with alle-style monorepos.
- If you do not have a paid subscription, the repo must be public
Setting up Greenkeeper to watch one of your repositories requries three steps:
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
Configureinstead. 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.
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.mdalready 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.
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
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, except for those you’ve explicitly disabled.
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:
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.1is 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.
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.
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.
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.
Out-of-range means: If you specify a range of
2.0.0is 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.
- It’s an in-range update, and your tests pass:
Greenkeeper verifies any pull requests
To prevent malicious users from posing as the Greenkeeper bot, Greenkeeper will attach a status check from
greenkeeper/verifyto 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:
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:
If it exists, delete the
greenkeeper/initialbranch on the repo.
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.
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 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.
Once you’ve pinned a package, every subsequent update to it will be considered out-of-range by Greenkeeper.Back to top
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
Greenkeeper supports lockfiles 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.
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
Back to top
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.