Skip to content
  • integrations
  • github

GitHub Integration

GitHub Integration

Section titled “GitHub Integration”

Connect GitHub to search issues, pull requests, discussions, and commits across your repositories.

What You Can Query

Section titled “What You Can Query”
Content TypeDescription
IssuesBug reports, feature requests, tasks
Pull RequestsCode reviews, changes, discussions
DiscussionsQ&A, announcements, ideas
CommitsCode changes with messages
CommentsConversation threads

Connecting GitHub

Section titled “Connecting GitHub”
  1. Log into TeamLoop at app.teamloop.io
  2. Navigate to Settings > Integrations
  3. Click Connect next to GitHub
  4. Authorize TeamLoop to access your repositories
  5. Select which organizations/repos to include

Permissions Requested

Section titled “Permissions Requested”

TeamLoop requests read-only access to:

  • Repository metadata
  • Issues and pull requests
  • Discussions
  • Commits and code

We never write to your repositories.

Example Queries

Section titled “Example Queries”

Search Issues

Section titled “Search Issues”
teamloop_query:
  query: "authentication bug"
  sources: "github"

Find Architecture Decisions

Section titled “Find Architecture Decisions”
teamloop_query:
  query: "ADR architecture decision record"
  sources: "github"

Search PRs by Topic

Section titled “Search PRs by Topic”
teamloop_query:
  query: "database migration"
  sources: "github"

Automatic Change Tracking

Section titled “Automatic Change Tracking”

TeamLoop automatically tracks changes from GitHub:

Issue Timeline

Section titled “Issue Timeline”

When you query an issue, TeamLoop fetches its changelog:

  • Status changes (open → closed)
  • Label changes
  • Assignee changes
  • Milestone changes

These are stored as CHANGE entities linked to the issue:

CHANGE: "Issue #123: Status changed to Closed"
  └── PART_OF → DOCUMENT: "Issue #123: Fix auth bug"

PR Events

Section titled “PR Events”

Pull request lifecycle events:

  • Review requests
  • Approvals
  • Merges
  • Status checks

Entity Extraction

Section titled “Entity Extraction”

GitHub content maps to TeamLoop entity types:

GitHubTeamLoop Entity
IssueDOCUMENT
PRDOCUMENT
DiscussionDOCUMENT
CommitCHANGE
Comment authorPERSON
Status changeCHANGE

Example Extraction

Section titled “Example Extraction”

From a GitHub issue about database migration:

{
  "entities": [
    {
      "type": "DOCUMENT",
      "name": "Issue #456: Migrate to PostgreSQL",
      "description": "Proposal to migrate user service from MySQL to PostgreSQL",
      "source_url": "https://github.com/org/repo/issues/456",
      "source_integration": "github",
      "source_external_id": "issues/456",
      "event_date": "2024-05-15"
    },
    {
      "type": "DECISION",
      "name": "Adopt PostgreSQL for user service",
      "rationale": "Need JSONB support and better performance",
      "alternatives": ["MySQL", "MongoDB"],
      "event_date": "2024-05-20"
    }
  ],
  "relationships": [
    {
      "source_name": "Adopt PostgreSQL for user service",
      "source_type": "DECISION",
      "target_name": "Issue #456: Migrate to PostgreSQL",
      "target_type": "DOCUMENT",
      "relationship_type": "PART_OF"
    }
  ]
}

Best Practices

Section titled “Best Practices”

1. Use Labels for Organization

Section titled “1. Use Labels for Organization”

TeamLoop can search by labels:

teamloop_query:
  query: "label:architecture label:decision"
  sources: "github"

2. Search Specific Repos

Section titled “2. Search Specific Repos”

Include repo context in queries:

teamloop_query:
  query: "repo:myorg/backend authentication"
  sources: "github"

3. Extract Decisions from PRs

Section titled “3. Extract Decisions from PRs”

PRs often contain implicit decisions. Extract them:

{
  "type": "DECISION",
  "name": "Use React Query for data fetching",
  "description": "Replaced manual fetch calls with React Query",
  "source_url": "https://github.com/org/frontend/pull/789"
}
Section titled “4. Link Changes to Documents”

Track how issues evolve:

teamloop_timeline:
  entity_id: "uuid-of-issue-document"

Temporal Queries with GitHub

Section titled “Temporal Queries with GitHub”

Point-in-Time

Section titled “Point-in-Time”

See what was known from GitHub on a specific date:

teamloop_query:
  query: "authentication"
  sources: "github"
  mode: "as_of"
  as_of: "2024-01-15"

Evolution

Section titled “Evolution”

Track how GitHub discussions evolved:

teamloop_evolution:
  query: "authentication github"
  from_date: "2024-01-01"
  to_date: "2024-12-31"

Troubleshooting

Section titled “Troubleshooting”

No Results

Section titled “No Results”
  • Check that the integration is connected
  • Verify you have access to the repositories
  • Try a broader search term
  • Check if the content is in private repos you authorized

Missing Repos

Section titled “Missing Repos”
  • Re-authorize with additional repo access
  • Check organization permissions in GitHub settings

Stale Data

Section titled “Stale Data”

GitHub data is fetched fresh on each query and cached. If you see stale data:

  • The cache may need to refresh (TTL: 7 days)
  • Recent changes may not be indexed yet

Rate Limits

Section titled “Rate Limits”

TeamLoop respects GitHub’s API rate limits:

  • 5,000 requests/hour for authenticated users
  • Queries are optimized to minimize API calls
  • Cached results reduce API usage

Security

Section titled “Security”
  • OAuth tokens are encrypted at rest
  • Tokens can be revoked from GitHub settings
  • TeamLoop only reads, never writes
  • You can disconnect at any time from TeamLoop settings

Next Steps

Section titled “Next Steps”