GitHub

Overview

Firefly integrates with GitHub to pull in information about your repositories, organizations, and related assets. This integration allows you to manage and monitor your GitHub resources as part of your Firefly Inventory, enabling you to enforce policies and maintain consistency across your GitHub assets.

Prerequisites

• A GitHub account with appropriate permissions

• A Personal Access Token (PAT) with the required scopes

• Access to the GitHub organizations you want to integrate

Setup Procedure

1. Log in to your GitHub account

2. Generate a Personal Access Token by visiting GitHub's token creation page with the following scopes:

Repository Scopes

• repo:status

• repo_deployment

• repo:invite

• public_repo

• security_events

Organization Scopes

• read:org

Public Key Scopes

• read:public_key

Repository Hook Scopes

• read:repo_hook

• notifications

User Scopes

• read:user

• user:email

Discussion Scopes

• read:enterprise

GPG Key Scopes

• read:gpg_key

1. In Firefly:

   • Navigate to Settings > Integrations

   • Select Add New > GitHub

   • Paste your Personal Access Token into the Access Token field

   • Select Next

   • Enter a descriptive name in the Nickname field

   • Select the desired Organization

   • Select Next > Done

Configuration Details

• Firefly scans your GitHub assets regularly to keep your inventory up to date

• You can enforce policies on your GitHub repositories and related assets

• The integration supports multiple GitHub organizations

• Your Personal Access Token is stored securely and encrypted

Best Practices

1. Use a dedicated GitHub account or organization for Firefly integration

2. Grant only the minimum required permissions to the Personal Access Token

3. Regularly rotate your Personal Access Token

4. Monitor the integration's activity in both Firefly and GitHub

5. Keep track of which repositories are being monitored

Troubleshooting

1. If the integration fails to connect:

   • Verify your Personal Access Token is valid and has the correct scopes

   • Check your network connectivity to GitHub

   • Ensure your GitHub account has access to the selected organization

2. If assets are not being discovered:

   • Verify the organization selection in Firefly

   • Check if the repositories are accessible to the integration account

   • Review the integration logs in Firefly

3. For token-related issues:

   • Generate a new Personal Access Token if the current one is compromised

   • Ensure the token hasn't expired

   • Verify all required scopes are enabled

Creating a Personal Access Token

1. Go to GitHub.com and log in to your account

2. Click your profile picture > Settings

3. Scroll down to Developer settings (bottom left)

4. Select Personal access tokens > Tokens (classic)

5. Click Generate new token > Generate new token (classic)

6. Give your token a descriptive name

7. Select the required scopes as listed above

8. Click Generate token

9. IMPORTANT: Copy the token immediately as you won't be able to see it again