node package manager



Get a stream of updates to a GitHub repository.

Build Status Dependency Status NPM version


npm install github-stream


To construct the stream use:

'use strict';
var Repository = require('github-stream');
var stream = new Repository(USER, REPO, options);
stream.on('data', function (update) {
  // { type: 'Directory', action: 'Create', path: '/my-dir' } 
  // { type: 'Directory', action: 'Delete', path: '/my-old-dir' } 
  // { type: 'File', action: 'Create', path: '/my-new-file', body: Buffer} 
  // { type: 'File', action: 'Update', path: '/my-file', body: Buffer} 
  // { type: 'File', action: 'Delete', path: '/my-old-file'} 

In order to keep track of updates, this module keeps the sha hashes of each file in memory. By default it polls github once every 10 seconds, but it correctly handles caching such that the requests only count when there are updates.

Note also that each file is transferred wholesale as a Buffer, not as a stream. This is much more convenient but can add significant memory footprint.


  • branch - The github branch to fetch, defaults to 'master'
  • auth - Optional access token to make requests with
  • updateFrequency - time to wait between polling (passed to the ms module, so it can be a string like '10s'), defaults to'10s'
  • retryFrequency - time to wait if the previus poll resulted in an error, defaults to the updateFrequency
  • state - the previous state of the repository, you can use this to optimise server restarts


In addition to the usual stream events, it also supports the following events:

  • 'state-updated' - emitted whenever the internal cache state has been properly updated. You can use this to persist between restarts.
  • 'error' - this is emitted whenever something goes wrong, but the polling continues even if there is an error.


  • stream.waitUntilReady() - returns a promise that is resolved once the repo has been fully synced
  • stream.dispose() - stop listening for updates