diff --git a/docs/guides/github/github-sidebar.json b/docs/guides/github/github-sidebar.json new file mode 100644 index 00000000..80a49139 --- /dev/null +++ b/docs/guides/github/github-sidebar.json @@ -0,0 +1,10 @@ +{ + "type": "category", + "id": "github", + "link": "guides/github", + "items": [ + "guides/github/import-organization", + "guides/github/real-time-events", + "guides/github/remove-organization" + ] +} \ No newline at end of file diff --git a/docs/guides/github/import-organization/allow-fine-grained-personal-access-tokens.png b/docs/guides/github/import-organization/allow-fine-grained-personal-access-tokens.png new file mode 100644 index 00000000..39128854 Binary files /dev/null and b/docs/guides/github/import-organization/allow-fine-grained-personal-access-tokens.png differ diff --git a/docs/guides/github/import-organization/associate-org-permission.png b/docs/guides/github/import-organization/associate-org-permission.png new file mode 100644 index 00000000..2122a9c0 Binary files /dev/null and b/docs/guides/github/import-organization/associate-org-permission.png differ diff --git a/docs/guides/github/import-organization/associated-permissions-in-pat.png b/docs/guides/github/import-organization/associated-permissions-in-pat.png new file mode 100644 index 00000000..aac2e062 Binary files /dev/null and b/docs/guides/github/import-organization/associated-permissions-in-pat.png differ diff --git a/docs/guides/github/import-organization/choose-location.png b/docs/guides/github/import-organization/choose-location.png new file mode 100644 index 00000000..60b12c49 Binary files /dev/null and b/docs/guides/github/import-organization/choose-location.png differ diff --git a/docs/guides/github/import-organization/connect-github-card.png b/docs/guides/github/import-organization/connect-github-card.png new file mode 100644 index 00000000..3a8d063b Binary files /dev/null and b/docs/guides/github/import-organization/connect-github-card.png differ diff --git a/docs/guides/github/import-organization/connect.png b/docs/guides/github/import-organization/connect.png new file mode 100644 index 00000000..3255fe3b Binary files /dev/null and b/docs/guides/github/import-organization/connect.png differ diff --git a/docs/guides/github/import-organization/copy-personal-token.png b/docs/guides/github/import-organization/copy-personal-token.png new file mode 100644 index 00000000..f3363452 Binary files /dev/null and b/docs/guides/github/import-organization/copy-personal-token.png differ diff --git a/docs/guides/github/import-organization/create-personal-token.png b/docs/guides/github/import-organization/create-personal-token.png new file mode 100644 index 00000000..bb270d13 Binary files /dev/null and b/docs/guides/github/import-organization/create-personal-token.png differ diff --git a/docs/guides/github/import-organization/edit-personal-token.png b/docs/guides/github/import-organization/edit-personal-token.png new file mode 100644 index 00000000..c5ccf095 Binary files /dev/null and b/docs/guides/github/import-organization/edit-personal-token.png differ diff --git a/docs/guides/github/import-organization/get-org-url.png b/docs/guides/github/import-organization/get-org-url.png new file mode 100644 index 00000000..34a49d63 Binary files /dev/null and b/docs/guides/github/import-organization/get-org-url.png differ diff --git a/docs/guides/github/import-organization/guardrails-console-login copy.png b/docs/guides/github/import-organization/guardrails-console-login copy.png new file mode 100644 index 00000000..3be50851 Binary files /dev/null and b/docs/guides/github/import-organization/guardrails-console-login copy.png differ diff --git a/docs/guides/github/import-organization/guardrails-console-login.png b/docs/guides/github/import-organization/guardrails-console-login.png new file mode 100644 index 00000000..3be50851 Binary files /dev/null and b/docs/guides/github/import-organization/guardrails-console-login.png differ diff --git a/docs/guides/github/import-organization/index.md b/docs/guides/github/import-organization/index.md new file mode 100644 index 00000000..487c9f0d --- /dev/null +++ b/docs/guides/github/import-organization/index.md @@ -0,0 +1,137 @@ +--- +title: Import Organization +sidebar_label: Import Organization +--- + +# Importing GitHub Organization + +In this guide, you will: + +- Learn how to import an entire GitHub organization into Turbot Guardrails. This process allows Guardrails to discover and manage resources across your organization in real-time. +- Monitor and troubleshoot the process. + +Importing a [GitHub Organization](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations) into Guardrails involves these key steps: + +- Configuring a GitHub with appropriate permissions at the Organization level. +- Importing the Organization via the Guardrails Console. + +## Prerequisites + +- Turbot Enterprise (TE) version `>=v5.48.x`, with the [GitHub mod](https://hub.guardrails.turbot.com/mods/github/mods) installed. +- Access to [GitHub](https://github.com/) and familiarity with its interface. +- Access to the Guardrails console with *Turbot/Owner* or *Turbot/Admin* permissions at the Turbot resource level. + +## Step 1: Set Personal Access Token Policy for Your Organization + +Setup the a personal access token policy for your organization prior to importing the organization into Guardrails. Refer steps provided in the GitHub [documentation](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). + +Choose `Allow access via fine-grained personal access tokens`. + +![Allow Fine-grained Personal Access Tokens](/images/docs/guardrails/guides/github/import-organization/allow-fine-grained-personal-access-tokens.png) + +## Step 2: Create Personal Access Token + +Turbot Guardrails supports both [Fine-grained](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) or [Classic](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic) GitHub token. This token is available in the GitHub portal under Developer settings and provide secure access to your resources. + +Follow the GitHub provided steps in [Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + +![Create Personal Token](/images/docs/guardrails/guides/github/import-organization/create-personal-token.png) + +Copy the personal access token. + +> [!IMPORTANT] +> Make sure to copy your personal access token during the creation step as you will not be able to see this again. + +![Copy Token](/images/docs/guardrails/guides/github/import-organization/copy-personal-token.png) + + +## Step 3: Grant Permissions + +Once you create a fine-grained token, initially it does not have any associated permission. + +![Personal Token with No Permission](/images/docs/guardrails/guides/github/import-organization/personal-token-with-no-permission.png) + +### Required Permissions + +To ensure full functionality of the GitHub integration, we recommend granting the following permissions: + +| **Permission** | **Access Level** | **Description** | +|--------------------------------------|---------------------|-------------------------------------------------------------------------------------------------------| +| Organization Administration | Read and write | Allows Guardrails to manage settings and configurations at the organization level. | +| Organization Webhooks | Read and write | Allows Guardrails to manage webhooks for capturing real-time events at the organization level. | +| Repository Metadata | Read-only | Provides Guardrails with visibility into repository metadata without modifying its content. | +| Repository Administration | Read and write | Grants Guardrails the ability to manage repository settings, including access controls and policies. | +| Organization Blocking Users | Read and write | Enables Guardrails to block and unblock users within the organization. | + +Select **Edit**, which allows to make edit in `Permissions` section. + +![Edit Personal Token](/images/docs/guardrails/guides/github/import-organization/edit-personal-token.png) + +Grant the [required permissions](#required-permissions) by selecting **All repositories** under `Repository access` and configuring the appropriate options in both **Repository permissions** and **Organization permissions** sections. + +![Associated Permission](/images/docs/guardrails/guides/github/import-organization/associate-org-permission.png) + +## Step 4: Validate Personal Access Token at Organization + +Navigate to your GitHub organization URL e.g. `https://github.com/organizations/adapt-cloud-security` and select **Settings**. + +![Organization Settings](/images/docs/guardrails/guides/github/import-organization/organization-settings.png) + +Navigate to **Personal access tokens** in left side panel, select **Active tokens**. + +![Org Personal Access Token](/images/docs/guardrails/guides/github/import-organization/select-active-tokens.png) + +It should display you the token created in the above step, select the token to check the required permissions are associated. + +![Associated Permissions](/images/docs/guardrails/guides/github/import-organization/associated-permissions-in-pat.png) + +## Step 5: Log in to Guardrails Console + +Log into the Guardrails console with provided local credentials or by using any SAML based login. + +![Guardrails Console Login](/images/docs/guardrails/guides/github/import-organization/guardrails-console-login.png) + +## Step 6: Import Organization into Guardrails + +Login to your Guardrails workspace console and select the **CONNECT** card. + +![Guardrails Console Login](/images/docs/guardrails/guides/github/import-organization/select-connect-card.png) + +Select **GitHub** card from the `Connect` panel. + +![Connect GitHub Card](/images/docs/guardrails/guides/github/import-organization/connect-github-card.png) + +Choose the folder where you want to import the organization. Typically this would be done at the `Turbot` root level of your hierarchy, however it can reside in a [Folder](/guardrails/docs/concepts/resources/hierarchy#folders) based on your use-case. + +![Choose Location](/images/docs/guardrails/guides/github/import-organization/choose-location.png) + +Get the Organization URL from GitHub **Overview** section. Copy the URL and past it in `Organization URL` text box. + +![Get Org URL](/images/docs/guardrails/guides/github/import-organization/get-org-url.png) + +Provide `Personal Access Token` and Select **Connect**. + +![Connect](/images/docs/guardrails/guides/github/import-organization/connect.png) + +## Step 7: Review + +- [ ] Check that the controls are executed by navigating to **Controls** tab and select GitHub. This should display the default controls for `Organization` and `Repository` in `OK` state. + +![Verify Controls](/images/docs/guardrails/guides/github/import-organization/verify-github-controls.png) + +## Next Steps + +Please see the following resources to learn more about Turbot Guardrails: + +- Learn more about [GitHub Event Handlers](/guardrails/docs/guides/github/real-time-events). +- Explore the GitHub supported use cases in Guardrails with [Policy Packs](https://hub.guardrails.turbot.com/policy-packs?providers=github). + +## Troubleshooting + +| **Issue** | **Description** | **Guide** | +|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| Controls in Error | Controls may enter various states, including errors, which can impact their functionality. | [Learn More About Control States](/guardrails/docs/concepts/controls#control-state) | +| Message: `Bad Credentials` | Guardrails GitHub controls may generate errors with a `Bad credentials` message, often caused by invalid or expired tokens. | [Token Expiration and Revocation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation) | +| Message: `forbids access via a personal access token with fine-grained permissions` | Guardrails GitHub controls may generate errors with a `forbids access` error, often caused, in case the used personal token does not have any required permissions. | Check the required permissions at [Importing GitHub Organization Required Permissions](#required-permissions) & more details at [Permissions required for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28) | +| Message: `Resource not accessible by personal access token .. list-users-blocked-by-an-organization` | Guardrails GitHub controls may generate errors with a `forbids accessResource not accessible by personal access token` | Check the required permissions at [Importing GitHub Organization Required Permissions](#required-permissions) & more details at [Permissions required for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28) | +| Further Assistance | If issues persist, please open a ticket with us and attach relevant details for more efficient troubleshooting. | [Open Support Ticket](https://support.turbot.com) | diff --git a/docs/guides/github/import-organization/organization-settings.png b/docs/guides/github/import-organization/organization-settings.png new file mode 100644 index 00000000..867263b6 Binary files /dev/null and b/docs/guides/github/import-organization/organization-settings.png differ diff --git a/docs/guides/github/import-organization/personal-token-with-no-permission.png b/docs/guides/github/import-organization/personal-token-with-no-permission.png new file mode 100644 index 00000000..b79d2e34 Binary files /dev/null and b/docs/guides/github/import-organization/personal-token-with-no-permission.png differ diff --git a/docs/guides/github/import-organization/personal-token.png b/docs/guides/github/import-organization/personal-token.png new file mode 100644 index 00000000..a9105a14 Binary files /dev/null and b/docs/guides/github/import-organization/personal-token.png differ diff --git a/docs/guides/github/import-organization/select-active-tokens.png b/docs/guides/github/import-organization/select-active-tokens.png new file mode 100644 index 00000000..6cb0804d Binary files /dev/null and b/docs/guides/github/import-organization/select-active-tokens.png differ diff --git a/docs/guides/github/import-organization/select-connect-card.png b/docs/guides/github/import-organization/select-connect-card.png new file mode 100644 index 00000000..67acbca8 Binary files /dev/null and b/docs/guides/github/import-organization/select-connect-card.png differ diff --git a/docs/guides/github/import-organization/verify-github-controls.png b/docs/guides/github/import-organization/verify-github-controls.png new file mode 100644 index 00000000..2755c27d Binary files /dev/null and b/docs/guides/github/import-organization/verify-github-controls.png differ diff --git a/docs/guides/github/index.md b/docs/guides/github/index.md new file mode 100644 index 00000000..41ab05a5 --- /dev/null +++ b/docs/guides/github/index.md @@ -0,0 +1,22 @@ +--- +title: Governing GitHub +sidebar_label: Governing GitHub +--- + +# Governing GitHub + +Turbot Guardrails provides comprehensive governance for [GitHub](https://github.com/), enabling secure, compliant, and efficient management of your GitHub resources. + +Guardrails ensures effective management and real-time visibility into your GitHub organizations with the following capabilities: + +- **Policy Management**: Offers a variety of GitHub mods with policies and controls to manage repositories, and organizations. +- **Real-Time Event Handling**: Updates the Guardrails CMDB as repositories, are created, modified, or deleted, enabling immediate policy enforcement. +- **Activity Visibility**: Provides insights into all activity within GitHub organizations, including who made changes, what was changed, and when it occurred. + +| Section | Description | +| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| [Import a GitHub Organization](guides/github/import-organization) | Guide to importing a GitHub organization into a Guardrails folder. | +| [Set Up GitHub Real-Time Events](guides/github/real-time-events) | How to configure Guardrails to process real-time GitHub events. | +| [Explore GitHub Mods](https://hub.guardrails.turbot.com/mods/github/mods) | A detailed list of available GitHub mods in Turbot Guardrails. | +| [Set Up GitHub Policies](https://hub.guardrails.turbot.com/policy-packs?providers=github) | Learn how to configure Guardrails policies for GitHub. | +| [Remove GitHub Organization](guides/github/remove-organization) | Guide to delete a GitHub organization from Guardrails. | diff --git a/docs/guides/github/real-time-events/control-configured-ok.png b/docs/guides/github/real-time-events/control-configured-ok.png new file mode 100644 index 00000000..a57df5b4 Binary files /dev/null and b/docs/guides/github/real-time-events/control-configured-ok.png differ diff --git a/docs/guides/github/real-time-events/create-event-handler.png b/docs/guides/github/real-time-events/create-event-handler.png new file mode 100644 index 00000000..7476c56c Binary files /dev/null and b/docs/guides/github/real-time-events/create-event-handler.png differ diff --git a/docs/guides/github/real-time-events/create-policy-setting.png b/docs/guides/github/real-time-events/create-policy-setting.png new file mode 100644 index 00000000..62ac6715 Binary files /dev/null and b/docs/guides/github/real-time-events/create-policy-setting.png differ diff --git a/docs/guides/github/real-time-events/guardrails-console-login.png b/docs/guides/github/real-time-events/guardrails-console-login.png new file mode 100644 index 00000000..3be50851 Binary files /dev/null and b/docs/guides/github/real-time-events/guardrails-console-login.png differ diff --git a/docs/guides/github/real-time-events/index.md b/docs/guides/github/real-time-events/index.md new file mode 100644 index 00000000..33081f72 --- /dev/null +++ b/docs/guides/github/real-time-events/index.md @@ -0,0 +1,76 @@ +--- +title: Real-Time Events +sidebar_label: Real-Time Events +--- + +# Configuring Real-Time Event Handlers + +In this guide, you will: + +- Set up Event Handlers in the Guardrails workspace using the Guardrails console. +- Monitor and troubleshoot the Event Handlers setup process. + +Guardrails enables organizations to selectively install policies, controls, and guardrails tailored to specific services. The [Event Handler](/guardrails/docs/reference/glossary#event-handler) simplifies cloud management by providing a unified framework for responding to and managing events, ensuring proactive governance and security across cloud environments. Event Handlers for GitHub are responsible for conveying events from GitHub back to Guardrails for processing. + +## Prerequisites + +- *Turbot/Operator* permissions at the Turbot level and familiarity with its interface. +- The GitHub organization has been successfully [imported](/guardrails/docs/guides/github/import-organization) into Guardrails. +- A GitHub personal access token with the necessary permissions to create [webhooks](https://docs.github.com/en/webhooks/about-webhooks). + +## Step 1: Grant Permission + +The personal access token used for importing an organization requires the `Organization Webhooks: Read and write` permission. This permission enables Guardrails to manage webhooks for capturing real-time events at the organization level. + +This permission is already granted during the [Required Permissions](/guardrails/docs/guides/github/import-organization#required-permissions) step of [Importing GitHub Organization](/guardrails/docs/guides/github/import-organization). + +## Step 2: Log in to Guardrails Console + +Log into the Guardrails console with provided local credentials or by using any SAML based login. + +![Guardrails Console Login](/images/docs/guardrails/guides/github/real-time-events/guardrails-console-login.png) + +## Step 3: Set Up Event Handlers Policy + +The GitHub Event Handlers are configured using the `GitHub > Organization > Event Handlers` control for each organization. This control sets up the required [webhooks](https://docs.github.com/en/webhooks/about-webhooks) components for the organization. + +Select the **Policies** tab. Search for `GitHub > Organization > Event Handlers` and select **New Policy Setting**. + +![Create Event Handler](/images/docs/guardrails/guides/github/real-time-events/create-event-handler.png) + +Select the `Resource` for the imported organization, set the policy to `Enforce: Enabled`, and select **Create**. + +![Set Policy to Enforced](/images/docs/guardrails/guides/github/real-time-events/create-policy-setting.png) + +## Step 4: Check Control Status + +Select the **Controls** tab. Search for `GitHub > Organization > Event Handlers` and check that the control status is `OK`. + +![Check Control Status](/images/docs/guardrails/guides/github/real-time-events/organization-event-handlers-control-status.png) + +## Step 5: Review + +- [ ] Check that the control status for the respective organization is `OK` with the message `Configured`. + +![Check Control Configured](/images/docs/guardrails/guides/github/real-time-events/control-configured-ok.png) + +- [ ] Verify that the webhook has been created in the GitHub organization. + +![GitHub Webhook](/images/docs/guardrails/guides/github/real-time-events/validate-github-org-webhook.png) + +## Next Steps + +Please see the following resources to learn more about Turbot Guardrails: + +- Learn more about [Managing GitHub Organizations](guides/github/manage-organizations). +- Explore the GitHub supported use cases in Guardrails with [Policy Packs](https://hub.guardrails.turbot.com/policy-packs?providers=github). + +## Troubleshooting + +| **Issue** | **Description** | **Guide** | +|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Controls in Error** | Controls may enter various states, including errors, which can impact their functionality. | [Learn More About Control States](/guardrails/docs/concepts/controls#control-state) | +| **Message: `Bad Credentials`** | Guardrails GitHub controls may generate errors with a `Bad credentials` message, often caused by invalid or expired tokens. | [Token Expiration and Revocation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation) | +| **Message: `forbids access via a personal access token with fine-grained permissions`** | Guardrails GitHub controls may generate this error when the personal token lacks the required permissions. | Check the required permissions at [Importing GitHub Organization Required Permissions](/guardrails/docs/guides/github/import-organization#required-permissions) & more details at [Permissions required for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28). | +| **Message: `Resource not accessible by personal access token .. list-users-blocked-by-an-organization`** | Guardrails GitHub controls may generate this error if the personal token lacks required permissions for the organization. | Check the required permissions at [Importing GitHub Organization Required Permissions](/guardrails/docs/guides/github/import-organization#required-permissions) & more details at [Permissions required for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28). | +| **Further Assistance** | If issues persist, please open a ticket with us and attach relevant details for more efficient troubleshooting. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/github/real-time-events/organization-event-handlers-control-status.png b/docs/guides/github/real-time-events/organization-event-handlers-control-status.png new file mode 100644 index 00000000..0845f2a5 Binary files /dev/null and b/docs/guides/github/real-time-events/organization-event-handlers-control-status.png differ diff --git a/docs/guides/github/real-time-events/repository-cmdb-controls.png b/docs/guides/github/real-time-events/repository-cmdb-controls.png new file mode 100644 index 00000000..38b924cb Binary files /dev/null and b/docs/guides/github/real-time-events/repository-cmdb-controls.png differ diff --git a/docs/guides/github/real-time-events/validate-github-org-webhook.png b/docs/guides/github/real-time-events/validate-github-org-webhook.png new file mode 100644 index 00000000..5b2724aa Binary files /dev/null and b/docs/guides/github/real-time-events/validate-github-org-webhook.png differ diff --git a/docs/guides/github/remove-organization/current-setting-enforce-enabled.png b/docs/guides/github/remove-organization/current-setting-enforce-enabled.png new file mode 100644 index 00000000..479f456a Binary files /dev/null and b/docs/guides/github/remove-organization/current-setting-enforce-enabled.png differ diff --git a/docs/guides/github/remove-organization/delete-github-config-pat-policy.png b/docs/guides/github/remove-organization/delete-github-config-pat-policy.png new file mode 100644 index 00000000..c64aa904 Binary files /dev/null and b/docs/guides/github/remove-organization/delete-github-config-pat-policy.png differ diff --git a/docs/guides/github/remove-organization/delete-organization.png b/docs/guides/github/remove-organization/delete-organization.png new file mode 100644 index 00000000..f54df9d7 Binary files /dev/null and b/docs/guides/github/remove-organization/delete-organization.png differ diff --git a/docs/guides/github/remove-organization/enforce-disabled.png b/docs/guides/github/remove-organization/enforce-disabled.png new file mode 100644 index 00000000..d210b834 Binary files /dev/null and b/docs/guides/github/remove-organization/enforce-disabled.png differ diff --git a/docs/guides/github/remove-organization/guardrails-console-login copy.png b/docs/guides/github/remove-organization/guardrails-console-login copy.png new file mode 100644 index 00000000..3be50851 Binary files /dev/null and b/docs/guides/github/remove-organization/guardrails-console-login copy.png differ diff --git a/docs/guides/github/remove-organization/guardrails-console-login.png b/docs/guides/github/remove-organization/guardrails-console-login.png new file mode 100644 index 00000000..3be50851 Binary files /dev/null and b/docs/guides/github/remove-organization/guardrails-console-login.png differ diff --git a/docs/guides/github/remove-organization/index.md b/docs/guides/github/remove-organization/index.md new file mode 100644 index 00000000..31d9ad22 --- /dev/null +++ b/docs/guides/github/remove-organization/index.md @@ -0,0 +1,84 @@ +--- +title: Remove Organization +sidebar_label: Remove Organization +--- + +# Removing GitHub Organization + +In this guide, you will: + +- Learn how to safely remove a GitHub organization from a Guardrails workspace. +- Monitor and troubleshoot the deletion process. + +Guardrails enables administrators to remove a [GitHub Organization](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations) from a workspace. This action deletes all associated policies and references in the Guardrails database but **does not affect any resources** within the source GitHub organization. + +> [!WARNING] +> Removing GitHub organization from Guardrails will remove all it's CMDB records and policy settings. + +## Prerequisites + +- **Turbot/Operator** permissions at the Turbot level and familiarity with its interface. +- Access to [GitHub](https://github.com/) and familiarity with its interface. + +## Step 1: Log in to Guardrails Console + +Log into the Guardrails console with provided local credentials or by using any SAML based login. + +![Guardrails Console Login](/images/docs/guardrails/guides/github/remove-organization/guardrails-console-login.png) + +## Step 2: Disable Event Handlers + +To safely remove your GitHub organization from the Guardrails workspace, disable the Event Handlers associated with `GitHub > Organization > Event Handlers` by setting the value to `Enforce: Disabled`. This action removes any Guardrails-configured webhooks in your GitHub organization. + +Go to the **Policies** tab. Search for `GitHub > Organization > Event Handlers` and verify the current status as `Enforce: Enabled`, then select the **Edit** button in the top-right corner. + +![Enforce Enabled](/images/docs/guardrails/guides/github/remove-organization/current-setting-enforce-enabled.png) + +Change the policy setting to `Enforce: Disabled` and select **Update** to save changes. + +![Enforce Disabled](/images/docs/guardrails/guides/github/remove-organization/enforce-disabled.png) + +## Step 3: Check GitHub Organization Webhooks + +The control status for `GitHub > Organization > Event Handlers` is `OK` and no webhooks configured as part of the event handler setup remain in your GitHub organization. + +![Removed Webhooks](/images/docs/guardrails/guides/github/remove-organization/removed-webhooks.png) + + +## Step 4: Remove Credential Policy + +Delete the `GitHub > Config > Personal Access Token` policy configured for the target GitHub organization. This ensures that Guardrails no longer has access to the organization. + +![Delete Personal Access Token Policy](/images/docs/guardrails/guides/github/remove-organization/delete-github-config-pat-policy.png) + + +## Step 5: Remove Organization + +Select the **Resources** tab in Guardrails console and enter your organization name in the search box to locate the resource. Navigate to the `Organization` that needs to be removed. + +![Locate Organization](/images/docs/guardrails/guides/github/remove-organization/locate-organization.png) + +Select the **Actions** button in the top-right corner and choose **Remove from Turbot**. + +![Remove from Turbot](/images/docs/guardrails/guides/github/remove-organization/remove-from-turbot.png) + +In the popup window, copy the resource name i.e. organization name and paste it into the text box. Select **Delete**. + +![Delete Organization](/images/docs/guardrails/guides/github/remove-organization/delete-organization.png) + +This completes the deletion of the organization from Guardrails. + + +## Step 6: Review + +Guardrails will begin the deletion process. The time required to complete the process depends on the number of policies and resources associated with the organization. Larger organizations may take longer. + +After completing the steps above, verify that the GitHub organization no longer appears in the Guardrails console. Ensure that no residual event handlers or configurations remain. + + +## Troubleshooting + +| **Issue** | **Description** | **Guide** | +|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| +| **Deletion Errors** | Errors may occur due to database locks or incomplete cleanup. Ensure all event handlers and policies have been removed before retrying. | [Troubleshooting](/guardrails/docs/guides/troubleshooting) | +| **Further Assistance** | If issues persist after troubleshooting, open a support ticket with details such as screenshots and error messages for efficient resolution. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/github/remove-organization/locate-organization.png b/docs/guides/github/remove-organization/locate-organization.png new file mode 100644 index 00000000..c0ced991 Binary files /dev/null and b/docs/guides/github/remove-organization/locate-organization.png differ diff --git a/docs/guides/github/remove-organization/remove-from-turbot.png b/docs/guides/github/remove-organization/remove-from-turbot.png new file mode 100644 index 00000000..f336b5c6 Binary files /dev/null and b/docs/guides/github/remove-organization/remove-from-turbot.png differ diff --git a/docs/guides/github/remove-organization/removed-webhooks.png b/docs/guides/github/remove-organization/removed-webhooks.png new file mode 100644 index 00000000..d5ebf6f1 Binary files /dev/null and b/docs/guides/github/remove-organization/removed-webhooks.png differ diff --git a/docs/guides/index.md b/docs/guides/index.md index 89a96783..dab8a76c 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -11,6 +11,7 @@ This section provides detailed step-by-step instructions on how to use Guardrail | [Governing AWS](guides/aws) | Guides to import AWS accounts and configure AWS-specific Guardrails features. | [Governing Azure](guides/azure) | Guides to import Azure accounts and configure Azure-specific Guardrails features. | [Governing GCP](guides/gcp) | Guides to import GCP projects and configure GCP-specific Guardrails features. +| [Governing GitHub](guides/github) | Guides to import GitHub organization and configure GitHub-specific Guardrails features. | [Governing Kubernetes](guides/kubernetes) | Guides to import Kubernetes clusters and configure Kubernetes-specific Guardrails features. | [Hosting Guardrails](guides/hosting-guardrails) | How to install and maintain the Enterprise version of Turbot Guardrails running in your own AWS account. | [Integrating ServiceNow](guides/servicenow) | How to install and manage Guardrail's ServiceNow CMDB sync. diff --git a/docs/sidebar.json b/docs/sidebar.json index 2c7e74d7..df4b8cea 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -276,6 +276,10 @@ } ] }, + { + "type": "placeholder", + "file": "guides/github/github-sidebar.json" + }, { "type": "category", "id": "kubernetes",