GitHub Configuration

Follow these steps to analyze GitHub repos and other objects with Cartography.

Step 1: Create a Personal Access Token

GitHub supports two types of Personal Access Tokens (PATs). We recommend using Fine-grained PATs as they provide more granular control and can be scoped to specific organizations.

Option A: Fine-grained PAT (Recommended)

Fine-grained PATs offer better security through minimal permissions and organization-level scoping.

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens

2. Click Generate new token

3. Configure the token:

   Setting	Value
   Token name	cartography-ingest (or your preference)
   Expiration	Per your security policy (90 days recommended)
   Resource owner	Select your organization (recommended)
   Repository access	All repositories

4. Set the following permissions:

   Repository permissions:

   Permission	Access	Required	Why
   Metadata	Read	Yes	Auto-added. Repository discovery and basic info.
   Contents	Read	Yes	Repository files, commit history, dependency manifests.
   Administration	Read	Recommended	Collaborators, branch protection rules. Without this, Cartography logs warnings and skips this data.

   Organization permissions:

   Permission	Access	Required	Why
   Members	Read	Yes	Organization members, teams, team membership, user profiles/emails.

5. Click Generate token and copy it immediately.

Note: When the token’s resource owner is an organization, user emails and profiles are retrieved from organization membership data. No account-level permissions are required.

Note: For collaborator and branch protection data, the token owner must also be an Organization Owner or have Admin access on repositories. The Administration: Read permission alone is not sufficient—the user must already have these rights.

Option B: Classic PAT

Classic PATs use broader OAuth scopes. Use this option if fine-grained PATs are not available (e.g., some GitHub Enterprise configurations).

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)

2. Click Generate new token

3. Select the following scopes:

   Scope	Why
   repo	Repository access (use public_repo for public repos only)
   read:org	Organization membership and team data
   read:user	User profile information
   user:email	User email addresses

4. Click Generate token and copy it immediately.

Optional: Additional Permissions for Full Data Access

Some data requires elevated permissions. Without these, Cartography will log warnings and continue ingestion, skipping the unavailable data.

Data	Requirement
Collaborators	The token owner must be an Organization Owner or have Admin access on the repositories. For fine-grained PATs, also add Administration: Read.
Branch protection rules	Same as collaborators - requires admin-level access.
Two-factor authentication status	Visible only to Organization Owners.
Enterprise owners	Requires GitHub Enterprise with appropriate enterprise-level permissions.

Step 2: Configure Cartography

Cartography accepts GitHub credentials as a base64-encoded JSON configuration. This format supports multiple GitHub instances (e.g., public GitHub and GitHub Enterprise).

1. Create your configuration object:

   import json
   import base64
   
   config = {
       "organization": [
           {
               "token": "ghp_your_token_here",
               "url": "https://api.github.com/graphql",
               "name": "your-org-name",
           },
           # Optional: Add additional orgs or GitHub Enterprise instances
           # {
           #     "token": "ghp_enterprise_token",
           #     "url": "https://github.example.com/api/graphql",
           #     "name": "enterprise-org-name",
           # },
       ]
   }
   
   # Encode the configuration
   encoded = base64.b64encode(json.dumps(config).encode()).decode()
   print(encoded)
   

2. Set the encoded value as an environment variable:

   export GITHUB_CONFIG="eyJvcmdhbml6YXRpb24iOi..."
   

3. Run Cartography with the GitHub module:

   cartography --github-config-env-var GITHUB_CONFIG
   

Configuration Options

CLI Flag	Description
--github-config-env-var	Environment variable containing the base64-encoded config
--github-commit-lookback-days	Number of days of commit history to ingest (default: 30)

GitHub Enterprise

For GitHub Enterprise, use the same token scopes/permissions as above. Set the url field in your configuration to your enterprise GraphQL endpoint:

{
    "token": "your_enterprise_token",
    "url": "https://github.your-company.com/api/graphql",
    "name": "your-enterprise-org",
}

Troubleshooting

Issue	Solution
FORBIDDEN warnings for collaborators	The token owner needs Organization Owner or Admin access on repos.
Empty dependency data	Ensure the dependency graph is enabled on your repositories.
Missing 2FA status	Only visible to Organization Owners.
Rate limiting	Cartography handles rate limits automatically by sleeping until the quota resets.