Skip to content
🤖 🌴 Real-time automated dependency updates for npm and GitHub
Branch: master
Clone or download
janl fix: runtime errors for repo-sync
- avoid using gh-queue because pagination, should not cause too many
issues, unless maybe folks have 10000s of repos.

- fix typo in github-queue error handling

- allow this to work outside of our staging organisation
Latest commit 1b5c7cd Mar 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Fix typo in May 2, 2018
content docs(payment-required): Update payment-required. pricing text Mar 14, 2019
utils fix: remove obsolete plan handling Feb 4, 2019
.editorconfig feat: initial May 20, 2017
.travis.yml feat: test on node 8 May 19, 2018 docs: add Contributing Guide and CoC Jan 23, 2018
Dockerfile feat: adjust to new deploy script Jul 31, 2018
index.js chore(package) update standard to the latest version Oct 5, 2018
start-couchdb chore: faster couchdb for tests Sep 27, 2018

Greenkeeper brings you safety & consistency with automatic updates and **real-time monitoring for npm dependencies**. Let a bot send you informative and actionable issues so you can easily keep your software up to date and in working condition.
Join over **10000 projects on GitHub that trust Greenkeeper** to warn them before dependency updates break their builds.
Who else is using it? Anyone I know?

Well, we’re helping out these fine folks, for example:

And many thousands more!

Tell me more about how Greenkeeper works, please!

No problem! Greenkeeper sits between npm and GitHub, observing all of the modules you depend on. When they get updated, your project gets a new branch with that update. Your CI tests kick in, and we watch them to see whether they pass.

Based on the test results and your current version definitions we will open up clear, actionable issues for you. If there’s nothing for you to do, we won’t nag you, but if a dependency does break your software, you’ll know immediately, and can get started on fixing the problem.

And if a you’ve got stuff to do, we understand. Sometimes you simply have to make a pragmatic trade-off between fixing your build for the breaking update or just pinning the working version so you can get back to it later. Our bot can respect that, and will let you pin the last working version of the dependency in the issue thread:

Screenshot - Pinning dependencies
Choosing repositories
I found a critical bug, who do I talk to?

If you’ve discovered a security-related bug in Greenkeeper or related services, please disclose it to us confidentially by emailing us at

If you find any, don’t share security vulnerabilities publicly (in a GitHub issue for example), always keep these conversations with us confidential so we have a chance to get things fixed before anyone exploits the bug.

Getting started with the new GitHub App

  1. Click on the green Install button at the top of the app page. If you’ve already done this, the button will be grey and labeled Configure.

  2. You can choose the specific organization to install Greenkeeper on, and have the option to enable individual repositories (we strongly recommend this), or all of the repositories.

    Important: just having the Greenkeeper installed on a repo doesn’t necessarily enable it. More on that below. By the way, you can change this behaviour on the Installed integrations page in your organizations’ settings.

    Screenshot - Installing Greenkeeper on repositories
    Choosing repositories
  3. If there’s a package.json file present in your repository you will get Greenkeeper’s initial pull request, which updates all outdated dependencies and contains a lot of additional information. Greenkeeper will only be enabled on this repo if you merge this initial pull request.

    Screenshot - Greenkeeper’s initial pull request
    Initial pull request

    Important: If all dependencies are already up-to-date, we won’t send this initial pull request. Instead, Greenkeeper will enable itself on the repo immediately, and you’ll start getting new issues on this repo only when Greenkeeper determines that there’s something for you to do. You can control this by only installing the app on the repos you actually need it on, using step 1. Again, we highly recommend taking the time to whitelist repos individually.

  4. That’s it. If a dependency breaks your build, Greenkeeper will let you know immediately. If not, it’ll stay out of your way. In any case, you get a more reliable software with minimum amount of work.

Additional Notes

  • With the new Greenkeeper public scoped npm packages work out of the box. Private scoped packages require an additional setup step, which is described in the initial pull request.

Jobs Service Documentation

This is the core service of Greenkeeper. It takes care of the dependency update logic and the related pull request/issue creation.

Job Types

🚨🚧 The following documentation might be outdated. We are currently working on improving this section.


The github-event job gets created by our hooks service. It's answering all incoming webhooks from GitHub and creates this job with the full payload from github as It only adds one additional type property to it with the name of the webhook event.


Depending on action a new entry is added/removed to/from the installations database. All repositories are requested from GitHub to sync them with our database. All repositories with a package.json receive their initial pull request (create-initial-branch).


Depending on action entries are added/removed to/from the repositories database. Added repositories with a package.json receive their initial pull request (create-initial-branch).


The package.json contents are retrieved, parsed and synced to our database.


If the status affects a Greenkeeper pull_request the results are recorded in our repositories database with all metadata.

If the status of a branch is failing, it will create a new branch to pin to the last working version create-pin-branch. When the status for that pin branch is coming, an issue is created with create-issue. If that issue already exists and it's still failing it will comment comment-issue, but if it's succeeding it will close that issue with close-issue.


When an initial Greenkeeper pull request is merged the repository gets enabled (enable-repository).

When a Greenkeeper pull request is merged older/included pull requests for the same dependency are closed (delete-older-branches). Unmergeable Greenkeeper pull requests get "rebased" (rebase-unmergeable-branches).


The registry-change job gets created by our changes service. It's listening for changes from npm and creates this job with the full payload from npm as

It figures out whether the change actually contains a new version, and on which dist-tag. It stores the versions in our npm database.

It figures out who is depending on the dependency that changed and schedules branch creation jobs for enabled ones. (create-version-branch)


Creates a branch for a dependency, pinning to the version before.


Creates an issue with the information that a dependency is failing.


Comments to an issue that a dependency is still failing.


Closes an issue because the dependency is no longer failing.


Used to be package-bump with our oAuth App.

If there are no tests detected, or the update is outside of the version range triggers create-version-pr right away.


Used to be package-send-pr with our oAuth App.


Deletes all branches related to a dependency which version is less or equal to the specified one.


Used to be package-pin with our oAuth App.


Used to happen inside webservice with our oAuth App.


Used to happen inside pull-request-close with our oAuth App.


Used to happen inside pull-request-close with our oAuth App.



  _id: '8422',  // github account id
  installation: 10, // installation id,
  plan: 'free', // plan
  login: 'finnp', // github name
  type: 'User' // 'User' or 'Organization'


type: repository

    _id: '111', // String(,
    type: 'repository',
    enabled: false,
    accountId: '8422', // account id (key for installations)
    fullName: 'greenkeeperio/jobs',
    private: true,
    fork: false,
    hasIssues: true,
    packages: {
          'package.json': {}


  _id: '111:branch:deadbeefdeadbeef', // repositoryId + sha
  type: 'branch',
  purpose: undefined, // can be 'pin', otherwise not defined
  sha: 'deadbeefdeadbeef',
  base: 'master', // base branch
  head: 'greenkeeper-lodash-8.0.0', // branch name
  dependency: 'lodash',
  version: '8.0.0',
  oldVersion: '~7.0.0',
  oldVersionResolved: '7.0.0',
  dependencyType: 'devDependencies',
  repositoryId: '111',
  accountId: '8422',
  processed: true, // the branch was processed
  referenceDeleted: true, // the branch reference was deleted
  state: 'failure', // ci status
  updated_at: '2016-09-28T15:07:03.022Z'


  _id: '111:pr:6', // repositoryId, PrId
  type: 'pr',
  repositoryId: 11,
  accountId: 42
  initial: true, // is this an initial pull request?
  number: 6,
  head: 'greenkeeper-lodash-8.0.0', // branch name
  state: 'open', // 'closed'
  merged: true,
  updated_at, '2016-09-28T15:07:03.022Z'


  _id: '111:issue:6',
  type: 'issue',
  repositoryId: '111',
  dependency: 'lodash',
  version: '1.0.0',
  number: 6,
  state: 'open',
You can’t perform that action at this time.