github-workhours

Analyze GitHub commit patterns to determine after-hours activity across an organization’s repositories.

Installation

npm install github-workhours

Or install globally to use the CLI:

npm install -g github-workhours

Configuration

The library and CLI use a GitHub Personal Access Token (PAT) to authenticate. You can provide your token in one of two ways:

1. Set the GITHUB_TOKEN environment variable:

   export GITHUB_TOKEN=your_token_here

2. Pass the token via the CLI flag:

   github-workhours -o my-org -t your_token_here

Rate Limiting & Caching

• Uses Bottleneck to stay within GitHub API rate limits.
• Default settings:
  • 5,000 requests per hour (refreshed hourly)
  • Maximum 5 requests per second
  • Single-request concurrency
• Flexible caching strategy:
  • In-memory cache (1 hour TTL) by default using node-cache
  • Redis cache (24 hour TTL) when REDIS_URL environment variable is set

Redis Configuration

To enable Redis caching, set the REDIS_URL environment variable:

export REDIS_URL=redis://localhost:6379

This will cache GitHub API responses for 24 hours, significantly reducing API usage for repeated analyses.

CLI Usage & Environment Variables

The CLI supports passing options via flags or environment variables.

github-workhours --help

Basic example (using flags):

The --since option accepts an ISO date or a natural language duration (e.g., --since "2 months").

github-workhours -o my-org -s 2023-01-01T00:00:00Z -u 2023-12-31T23:59:59Z

Or using environment variables:

export GITHUB_ORG=my-org
export GITHUB_TOKEN=your_token_here
github-workhours

Sample output (JSON):

{
  "org": "my-org",
  "since": "2023-01-01T00:00:00Z",
  "until": "2023-12-31T23:59:59Z",
  "analysis": {
    "alice": {
      "byHour": [ ... ],
      "byDay": [ ... ],
      "totalCommits": 123,
      "afterHoursCommits": 45
    },
    "bob": { ... }
  }
}

Programmatic API

const { analyzeWorkHours } = require('github-workhours');

(async () => {
  const result = await analyzeWorkHours({
    org: 'my-org',
    since: '2023-01-01T00:00:00Z',
    until: '2023-12-31T23:59:59Z',
    token: process.env.GITHUB_TOKEN
  });
  console.log(result);
})();

Examples

An example script is provided in examples/run-analysis.js:

node examples/run-analysis.js

Development & Testing

Clone the repo and install dependencies:

git clone https://github.com/your-org/github-workhours.git
cd github-workhours
npm install

Run tests:

npm test

License

MIT