docs: function() {
              auth.type = 'oauth';        // @todo this gets reset to basic during getBasicAuth() check
  
              // If a valid token has been passed then just use that to authenticate
              if ( octofish.config.auth.token ) {
                  auth.token = octofish.config.auth.token;
                  storeAuth( auth );
                  cb_success();
                  return;
              }
  
              // If we got here then we'll have to request a valid token from github which will require basic authentication
              // Perform basic authorisation and bail on fail
              if ( !getBasicAuth() ) {            // @todo only validates that username and password have been specified
                  console.warn( 'Basic auth is required to use oAuth but...' );
                  console.warn( 'Basic authentication failed --- can not proceed with oauth' );
                  cb_failure();
                  return;
              }
  
              // Build oauth object to request auth token
              // Auth token is added to the object on success and passed to storeAuth() to authenticate with
              // @todo Not all of these parameters are required to request a token
              // @todo scopes in the config must be set closed up (no whitespace) - add utility function to strip whitespace
              auth.type = 'basic';            // This is included for code clarity - getBasicAuth() above will already have set this
              auth.client_ID = process.env.oauthKEY || octofish.config.auth.KEY || '';
              auth.client_secret = process.env.oauthSECRET || octofish.config.auth.SECRET || '';
              octofish.config.auth.scope ? auth.scopes = octofish.config.auth.scope.split(',') : '';
              auth.note = octofish.config.auth.note;
              auth.note_url = octofish.config.auth.note_url;
  
              // Authenticate using oauth
              octofish.github.authorization.create( auth, function( err, res) {
                  if ( err ) {
                      console.warn( 'Error using oAuth' );
                      console.log( 'oAuth object used to authenticate: ');
                      console.dir( auth );
                      console.log( 'Error returned: ');
                      console.log( err );
                      cb_failure();
                      return;
                  }
  
                  console.log( 'Authenticating to github with oAuth --- success' );
                  auth.token = res.token;
                  storeAuth( auth );
  
                  cb_success();
              });
          }