GitHub Plugin Configuration Guide

This guide explains how to configure the ActivityPulse GitHub plugin to fetch activity data from your GitHub instance.

Prerequisites

• GitHub account with access to repositories you want to track
• Personal Access Token with appropriate scopes
• GitHub instance URL (github.com or GitHub Enterprise Server)

Overview

The GitHub plugin uses the GitHub REST API to fetch activity data. This requires:

1. GitHub URL - The base URL of your GitHub instance
2. Personal Access Token - A PAT with read access to the API

Step 1: Create a Personal Access Token

1.1 Navigate to Token Settings

1. Log in to your GitHub instance
2. Click your avatar in the top-right corner
3. Select Settings
4. In the left sidebar, scroll down and click Developer settings
5. Click Personal access tokens > Tokens (classic)

1.2 Create New Token (Classic)

1. Click Generate new token > Generate new token (classic)
2. Enter a Note (e.g., ActivityPulse)
3. Set an Expiration (recommended: 90 days or 1 year)
4. Select the following scopes:

Scope	Purpose
repo	Full control of private repositories (read access to code, commits, PRs, issues)
read:user	Read user profile information

Note: If you only need to track public repositories, the public_repo scope is sufficient instead of repo.

5. Click Generate token

1.3 Alternative: Fine-Grained Token

1. Click Generate new token > Generate new token (fine-grained)
2. Enter a Token name and Expiration
3. Under Repository access, select the repositories to track
4. Under Permissions, grant:
   • Repository permissions: Contents (Read), Issues (Read), Pull requests (Read), Metadata (Read)
   • Account permissions: (none required)
5. Click Generate token

1.4 Copy the Token

IMPORTANT: Copy the token immediately. You will NOT be able to see it again.

Store it securely - you’ll need it for ActivityPulse configuration.

Step 2: Configure ActivityPulse

2.1 Enter Configuration in ActivityPulse

In the ActivityPulse web interface:

1. Navigate to Data Sources
2. Click Add Data Source or edit an existing GitHub source
3. Enter the values:

Field	Value	Example
GitHub URL	Base URL of your GitHub instance	https://github.com
API Token	Personal Access Token from Step 1	ghp_xxxxx
Jira URL (Optional)	Jira instance for issue linking	https://company.atlassian.net

4. Click Save Configuration

2.2 Map Users

For each team member you want to track:

1. Navigate to Teammates
2. Edit the team member
3. In the External IDs section, add their GitHub identifier
4. Enter their GitHub username (e.g., octocat)

Data Collected

The GitHub plugin collects the following activity data:

Pull Requests

• PRs opened, merged, closed, and reopened
• PR reviews (approved, changes requested, commented)
• PR comments

Commits

• Commits pushed to repositories
• Commit messages and timestamps
• Lines added/removed

Issues

• Issues opened, closed, and reopened
• Issue comments

Branches

• Branches created and deleted

Signals

• Open pull requests assigned to each teammate
• Open issues assigned to each teammate

Verification

Test the Connection

1. In ActivityPulse, go to Data Sources
2. Find your GitHub data source
3. Click Test Connection
4. A successful test confirms the API token is valid

Verify Data Collection

1. Click Fetch to trigger immediate data collection
2. Go to Activities to see fetched activity data
3. Filter by source type “GitHub” to see only GitHub activities

Troubleshooting

”Authentication failed” Error

• Verify the API token is copied correctly (no leading/trailing spaces)
• Ensure the token hasn’t expired
• Check that the token has the required scopes (repo, read:user)

“Not found” Errors

• Verify the GitHub URL is correct and accessible
• For GitHub Enterprise Server, ensure the API is enabled
• Check that the token has access to the relevant repositories

No Data After Fetch

• Verify team members have GitHub external IDs configured
• Ensure the API token owner has access to the relevant repositories
• Check that users have recent activity in the configured date range
• Note: GitHub’s Events API only returns the last 300 events (up to 90 days)

Rate Limiting

• GitHub allows 5,000 API requests per hour for authenticated users
• The search API has a separate limit of 30 requests per minute
• ActivityPulse handles rate limiting automatically with retries
• If persistent, consider using a fine-grained token with limited repository access

Jira Integration (Optional)

If you use Jira for issue tracking and reference Jira issues in GitHub:

1. Set the Jira URL in the GitHub configuration
2. Jira issue references in branch names (e.g., feature/ABC-123-add-login) will be automatically linked
3. Jira references in commit messages and PR titles will also be linked

This allows you to see Jira context directly in your GitHub activities.

GitHub Enterprise Server

For GitHub Enterprise Server (GHES) instances:

1. Set the GitHub URL to your GHES base URL (e.g., https://github.company.com)
2. The plugin automatically uses the correct API endpoint ({base_url}/api/v3)
3. Ensure your GHES instance has API access enabled

Security Best Practices

Token Management

• Use dedicated tokens for ActivityPulse (not your personal tokens for other tools)
• Set reasonable expiration dates and rotate tokens before expiry
• Store tokens securely using a password manager
• Consider using fine-grained tokens for minimal access

Minimal Permissions

• Only grant repo (or public_repo) and read:user scopes
• Do not grant write permissions unless specifically needed
• For fine-grained tokens, only select the repositories you need to track

Self-Hosted Instances

• Ensure your GitHub Enterprise Server uses HTTPS
• Consider IP allowlisting if your instance supports it
• Monitor token usage in your GHES admin dashboard

API Rate Limits Reference

API	Limit	Notes
REST API (authenticated)	5,000 requests/hour	Per token
Search API	30 requests/minute	Stricter limit
Events API	300 events max	Per user, up to 90 days

Additional Resources

• GitHub Personal Access Tokens
• GitHub REST API Documentation
• GitHub API Rate Limits