Skip to main content
GitHub

GitHub

Discover GitHub repositories, organizations, and users. Provides MCP tools for GitHub operations.

The GitHub molecule automatically syncs GitHub data into your SixDegree ontology and gives AI agents tools to interact with GitHub repositories.

  • SixDegree Platform installed
  • GitHub personal access token with repo scope
  • For GitHub Enterprise: custom API URLs

discovery:
  enabled: true
  settings:
    # GitHub API credentials
    token: "ghp_your_github_token"

    # Optional: GitHub Enterprise URLs
    api_url: "https://api.github.com"
    base_url: "https://github.com"

    # Organizations to discover
    selectors:
      - organization: "your-org"
        repo_pattern: ".*"  # Regex: all repos
        graph_files:
          - ".sixdegree.yaml"  # Read graph definitions from repos

      - organization: "another-org"
        repo_pattern: "^backend-.*"  # Only backend repos

    # Optional: Webhook configuration
    webhook:
      secret: "your_webhook_secret"
      events:
        - push
        - pull_request
        - repository

mcp:
  enabled: true
  settings:
    token: "ghp_your_github_token"
    api_url: "https://api.github.com"
    scopes:
      - repo
      - issues
      - pulls

namespace: "production"

The GitHub molecule discovers:

  • github.com/v1/Repository - GitHub repositories with metadata (stars, language, description)

  • github.com/v1/Organization - GitHub organizations

  • github.com/v1/User - GitHub users

  • owns - Organization owns Repository

  • memberOf - User is member of Organization

  • contributesTo - User contributes to Repository

Repositories can include a .sixdegree.yaml file that defines additional entities and relationships. The molecule will read these files and add the custom graph data to your ontology.

Example .sixdegree.yaml in a repository:

entities:
  - type: service.example.com/v1/API
    id: user-service-api
    name: User Service API
    attributes:
      endpoint: https://api.example.com/users

relations:
  - from: user-service-api
    to: repository:my-org/user-service
    type: IMPLEMENTED_IN

AI agents can use these GitHub tools:

Create a new issue in a repository.

Parameters:

  • repo (string, required) - Repository in owner/repo format
  • title (string, required) - Issue title
  • body (string, optional) - Issue description in Markdown
  • labels (array, optional) - Array of label names

Example:

User: "Create a GitHub issue in myorg/myrepo about the login bug"

AI: [Calls github_create_issue]
    "✅ Created issue #123: Fix login bug
     https://github.com/myorg/myrepo/issues/123"

Create a new pull request.

Parameters:

  • repo (string, required) - Repository in owner/repo format
  • title (string, required) - PR title
  • body (string, optional) - PR description in Markdown
  • head (string, required) - Source branch
  • base (string, required) - Target branch
  • draft (boolean, optional) - Create as draft PR

Example:

User: "Create a PR from feature-auth to main"

AI: [Calls github_create_pull_request]
    "✅ Created PR #45: Add authentication feature
     https://github.com/myorg/myrepo/pull/45"

Get the contents of a file from a repository.

Parameters:

  • repo (string, required) - Repository in owner/repo format
  • path (string, required) - File path in repository
  • ref (string, optional) - Git ref (branch, tag, or commit SHA)

Example:

User: "What's in the README of myorg/myrepo?"

AI: [Calls github_get_file_contents]
    "The README contains: [file contents]"

Runs on schedule to discover repositories and users:


degree discovery run github@1.0.0 --config github-config.yaml


degree discovery schedule github@1.0.0 --config github-config.yaml --interval 5m

Real-time updates via GitHub webhooks:

  1. Configure webhook secret in your config
  2. Deploy webhook endpoint with SixDegree
  3. Add webhook to GitHub organization settings:
    • Payload URL: https://your-sixdegree.com/webhooks/github
    • Content type: application/json
    • Secret: Your webhook secret
    • Events: push, pull_request, repository

degree discovery run github@1.0.0 --config github-config.yaml


degree discovery run github@1.0.0 --config github-config.yaml --dry-run


GITHUB_LOG_LEVEL=debug degree discovery run github@1.0.0 --config github-config.yaml

Once configured, AI agents can use GitHub tools:

You: "Create an issue in myorg/api-service about rate limiting"

AI: ✅ Created issue #89: Implement rate limiting
    https://github.com/myorg/api-service/issues/89

You: "What files are in the src/ directory of myorg/frontend?"

AI: [Uses github_get_file_contents to explore]
    Found: src/App.js, src/index.js, src/components/...

cd github
go build -o ../bin/github


cd ..
make dev

For GitHub Enterprise installations:

discovery:
  settings:
    api_url: "https://github.enterprise.com/api/v3"
    base_url: "https://github.enterprise.com"
    token: "ghp_enterprise_token"

Required GitHub token scopes:

  • Discovery: repo (read repositories), read:org (read organizations)

  • MCP Tools:

    • repo - File contents
    • issues - Create/read issues
    • pulls - Create/read pull requests

  • Store tokens as secrets in your configuration

  • Use separate tokens for discovery and MCP if needed

  • Limit token scopes to minimum required permissions

  • Use webhook secrets to verify webhook authenticity

  • For production, use GitHub Apps instead of personal access tokens

"Not Found" errors:

  • Check token has access to the organization
  • Verify organization name is correct
  • Ensure token has required scopes

Missing repositories:

  • Check repo_pattern regex matches repository names
  • Verify token has access to private repositories
  • Enable debug logging to see what's being discovered

Webhook not triggering:

MIT - See LICENSE file in molecules directory