Initial skeleton structure for GitHub

docs/guides/github/decommission/index.md

@@ -0,0 +1,63 @@
+---
+title: Decommission GitHub Organization
+sidebar_label: Decommission GitHub Organization
+---
+
+# Decommission GitHub Organization
+
+In this guide, you will:
+- Learn how to decommission a GitHub organization from a Guardrails workspace while managing associated resources effectively.
+
+Guardrails allows administrators to remove a GitHub organization from a workspace. The delete action removes all associated policies and references from the Guardrails database, but **does not delete any resources** from the target GitHub organization. Careful consideration should be made when managing resources such as webhooks, permissions, and audit logs, as once removed, these changes cannot be undone.
+
+Before starting the process, administrators should determine whether Guardrails-managed resources (e.g., webhooks, event subscriptions) should remain in the organization. The following policies can be configured in Guardrails to facilitate cleanup. Ensure that these changes are applied **only to the target GitHub organization**.
+
+1. `GitHub > Turbot > Permissions` set to `Enforce: None`. This removes Guardrails-managed roles and permissions in the organization.
+2. `GitHub > Turbot > Event Handlers > Webhooks` set to `Enforce: Not Configured`. This removes Guardrails-configured webhooks.
+3. `GitHub > Turbot > Event Poller` set to `Disabled`. This disables the polling of events into Guardrails.
+
+Once these policies have been applied and the associated controls have completed their cleanup, the GitHub organization can be safely removed from the Guardrails workspace. You can customize these policies to target specific resources while retaining essential audit data.
+
+
+## Prerequisites
+
+- **Turbot/Operator** permissions at the Turbot resource level.
+- Familiarity with the Guardrails console.
+
+
+## Step 1: Remove Credentials Policies
+Delete the policies `GitHub > Client Secret` and `GitHub > App Key` configured for the target GitHub organization. This ensures that Guardrails no longer has access to the organization.
+
+## Step 2: Log in to the Guardrails Console
+Log in to the Guardrails console.
+
+![Guardrails Console Login](/images/docs/guardrails/guides/github/decommission-github-organization/guardrails-console-login.png)
+
+## Step 3: Navigate to the Organization
+Using the Guardrails console, navigate to the GitHub organization that needs to be removed.
+
+## Step 4: Delete the Organization
+1. Click the **Delete** button in the top-right corner. If you don’t see this button, contact your Guardrails administrator for the required permissions.
+2. In the popup window, copy the organization ID and paste it into the text box.
+3. Click **Delete**. While the deletion is reversible by re-importing the organization, it can be resource-intensive. Double-check all configurations before proceeding.
+
+## Step 5: Verify Deletion
+Guardrails will begin the deletion process. The time 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.
+
+
+## Next Steps
+
+Please see the following resources to learn more about Turbot Guardrails:
+
+- Learn more about [Managing GitHub Organizations](guides/github/manage-organizations).
+- Learn about [Permissions Policies for GitHub](guides/github/permissions).
+
+
+## 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.                                          | [Troubleshoot Deletion Issues](/guardrails/docs/github/troubleshooting#deletion-errors) |
+| **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)   |

docs/guides/github/import-github-organization/index.md

@@ -0,0 +1,58 @@
+---
+title: Import GitHub Organization
+sidebar_label: Import GitHub Organization
+---
+
+# Import GitHub Organization
+
+In this guide, you will:
+
+- This guide provides step-by-step instructions to import a GitHub organization into a Guardrails folder, ensuring that your GitHub environment is governed according to your organizational policies.
+
+Turbot Guardrails enables seamless integration with GitHub, allowing you to manage your GitHub organizations, repositories, teams, and access permissions effectively. By importing a GitHub organization into Guardrails, you gain the ability to:
+
+- Centralize governance for your GitHub resources within Guardrails.
+- Apply policies to enforce security, compliance, and operational best practices.
+- Monitor real-time activity within your organization, including changes to repositories, teams, and permissions.
+- Automate the enforcement of IAM roles and permissions, ensuring users have appropriate access levels.
+- Establish detailed audit logs to track all activities and changes for improved visibility and reporting.
+
+## Prerequisites
+
+- **Turbot/Operator** permissions at the Turbot resource level.
+- Familiarity with the Guardrails console.
+
+
+## Step 1: Get GitHub Organization ID
+
+
+## Step 2: Login to Guardrails Console
+
+Log in to the Guardrails console.
+
+![Guardrails Console Login](/images/docs/guardrails/guides/github/import-github-organization/guardrails-console-login.png)
+
+## Step 3: Navigate to Connect
+
+
+## Step 4:
+
+## Step 5:
+
+## Step 6:
+
+## Verify
+
+## Next Steps
+
+Please see the following resources to learn more about Turbot Guardrails Enterprise:
+
+- Learn more about [TODO].
+- Learn about [TODO]
+
+## Troubleshooting
+
+| Issue                                      | Description                                                                                                                                                                                                 | Guide                                |
+|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
+| Permission Issues                        | If the current logged-in user lacks permission to modify, update, or create resources in the stack, or if IAM roles or SCPs have changed, preventing built-in roles from accessing needed configuration settings.   | [Troubleshoot Permission Issues](/guardrails/docs/enterprise/FAQ/admin-permissions#aws-permissions-for-turbot-guardrails-administrators)             |
+| Further Assistance                       | If you continue to encounter issues, please open a ticket with us and attach the relevant information to assist you more efficiently.                                                 | [Open Support Ticket](https://support.turbot.com)   |

docs/guides/github/index.md

@@ -0,0 +1,30 @@
+---
+title: Governing GitHub
+sidebar_label: Governing GitHub
+---
+
+TO REVIEW FURTHER TO CHANGE
+
+# 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, teams, and organizations.
+- **Permission Management**: Extensive IAM integration to manage GitHub permissions, ensuring appropriate user access to repositories and teams.
+- **Real-Time Event Handling**: Updates the Guardrails CMDB as repositories, teams, and permissions 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-github-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. |
+| [Enable GitHub Features](guides/github/features) | Steps to enable the GitHub features required for governance. |
+| [Configure Permissions Policies](guides/github/permissions) | How to configure policies to manage GitHub permissions effectively. |
+| [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. |
+| [Learn About Permissions](concepts/iam/permissions) | Information on managing permissions in Guardrails. |
+
+---
+
+This structure aligns closely with the style and format of the **Hosting Guardrails** content, providing a professional and concise layout for easy navigation.

docs/guides/github/permissions/index.md

@@ -0,0 +1,186 @@
+---
+title: Permissions
+sidebar_label: Permissions
+---
+
+# Managing GitHub Permissions
+
+In this guide, you will:
+- Learn how to retrieve and analyze access logs to investigate control failures in the Guardrails console.
+
+
+Turbot Guardrails provides a rich set of capabilities for managing authentication of users,
+as well as authorization to GCP services and resources. Guardrails integrates with
+GCP IAM Identity and Access Management to provide a simple but flexible model
+for managing access to your GCP projects using native GCP IAM Roles.
+
+Permissions policies are used to customize which levels are available to assign
+permissions, as well as the set of operations that those levels encompass. Refer
+to the [permissions core concepts](concepts/iam/permissions) documentation for
+more information.
+
+## Enabling GCP permissions
+
+To enable full GCP permissions management through Guardrails with a default
+configuration, set the `GCP > Turbot > Permissions` policy to "Enforce: Role
+Mode":
+
+```hcl
+resource "turbot_policy_setting" "gcp_permissions" {
+  resource        = "id of project or parent folder or policy pack"   //highlight-line
+  type            = "tmod:@turbot/gcp-iam#/policy/types/permissions"
+  value           = "Enforce: Role Mode"
+}
+```
+
+### Permissions Modes
+
+Guardrails can be configured to operate in one of 2 permissions modes:
+
+- **None:** Guardrails Managed GCP Permissions defaults to off. This allows you to
+  use the other Guardrails controls but manage GCP Authentication and Authorization
+  entirely on your own.
+
+- **Role Mode:** Role Mode provides a full set of GCP permissions management
+  capabilities using IAM roles. Guardrails will create roles and bindings in each
+  project to manage permissions. You can assign permissions to Guardrails console users,
+  then Guardrails will map the users the role(s) assigned to them.
+
+## Standard Levels
+
+The `Permissions > Levels` policies configure which standard Guardrails
+roles/groups/policies will be created. Levels enabled in this policy will appear
+in the Guardrails console, and can be assigned to a user in the Permissions tab.
+
+This gives you a large degree of control about what rights can be granted in
+your organization -- You can choose to disable levels that don't apply. Example
+use cases:
+
+- My Organization does not use the `GCP/User` permission, so I don't want it to appear in the Guardrails Permissions tab.
+- My Organization only assigns access using the `GCP/*` permissions, and I don't
+  want the overhead of creating and managing all service-specific options
+  (`GCP/Storage/*`, `GCP/Compute/*`, etc.).
+
+Standard permission levels are:
+
+- **User**
+- **Metadata**
+- **ReadOnly**
+- **Operator**
+- **Admin**
+- **Owner**
+- **SuperUser** [not applicable ton individual services]
+
+Project-level permission level policies (GCP/Admin, GCP/Metadata, etc) can be
+configured in `GCP > Permissions > Levels`. By default, all levels are enabled.
+
+Permission level policies for each service (GCP/Storage/Admin,
+GCP/Storage/Metadata, etc.) can be configured in
+`GCP > {service} > Permissions > Levels`.
+
+<div className="example">
+  <ul>
+    <li><code> GCP > Storage > Permissions > Levels </code></li>
+    <li><code> GCP > Compute > Permissions > Levels </code></li>
+  </ul>
+</div>
+
+You can use the `GCP > Permissions > Levels [Default]` policy to configure the
+default levels for _all_ services. By default, service-level permissions are
+_not_ enabled.
+
+## Modifiers
+
+Permission Level Modifiers provide a simple mechanism to modify the standard
+permissions policies. Modifiers work with Guardrails' IAM rules
+engine to modify the access directly in the Guardrails IAM policies.
+
+You can use Modifiers to:
+
+- Change what permissions levels a specific api path is assigned
+- Remove access at a give permissions level
+- Add access to APIs that are not currently supported by Guardrails
+
+Modifier example use-cases:
+
+- I want to add access to a new API in Storage that Guardrails doesn't support yet
+- I want to add an entirely new service that Guardrails doesn't support yet
+- I want to add a capability for my Compute Operators that Guardrails normally
+  reserves for Admins
+- Guardrails assigns an GCP permission to `Compute/Operator` that I consider
+  privileged - I want to reassign that permission to Compute Admins
+
+Modifiers leverage the existing Guardrails rules engine to modify the default Guardrails policies. They do not
+generate separate IAM policies.
+
+Modifiers can add, remove, and change permissions for any GCP service to any
+standard permission level. Modifiers effectively redefine (override) the
+permission level to which an api operation is defined.
+
+- Permissions defined in the Modifiers policy override the Guardrails defaults
+- Permissions defined in the Modifiers policy override the Guardrails Capability
+  Modifier Policies
+
+Modifiers are cumulative in the same way that levels are - if you add a
+permission to the **Metadata** level, it is also added to **ReadOnly**,
+**Operator** and **Admin**
+
+Modifier policies exist for both GCP levels and per-service levels
+
+- Modifier policies at the provider level (GCP/Admin, etc) apply ONLY at the GCP
+  level
+  - `GCP > Permissions > Levels > Modifiers`
+- Modifier policies at the service level will “roll up” to the provider level
+  too -- for example if you add a permission to **GCP/Storage/Operator**, it
+  will be assigned to **GCP/Operator** as well.
+  <div className="example">
+    <ul>
+      <li><code> GCP > Storage > Permissions> Levels> Modifiers </code></li>
+      <li><code> GCP > Computed > Permissions> Levels> Modifiers </code></li>
+    </ul>
+  </div>
+
+## Capability Modifier Policies
+
+**Capability Modifier** policies allow you to either restrict access to certain
+sets of actions to Guardrails, or to allow them to admin users as appropriate.
+Capability modifiers are essentially Modifiers that are pre-defined in Guardrails.
+These policies are often used to force administration of resources through the
+Guardrails control plane, and disallow direct access to the underlying GCP APIs from
+users.
+
+The Capability Modifier Policies are applied after the built-in permissions but
+before the custom Modifiers:
+
+- Capability Modifier Policies override Guardrails' default permissions assignments
+- Custom Modifiers override Capability Modifier Policies
+
+  <div className="example">
+    <ul>
+      <li><code> GCP > Storage > Permissions > Levels > ACL Administration`</code></li>
+      <li><code> GCP > Storage > Permissions > Levels > Access Logging Administration </code></li>
+    </ul>
+  </div>
+
+## Custom Levels
+
+Custom Levels provide another mechanism to provide flexibility in managing GCP
+permissions. Whereas Modifiers and Custom Policies allow you to customize the
+rights granted to Guardrails built-in permissions levels, Custom Levels allow you to
+create _your own_ levels that you can use to assign access through the Guardrails
+console.
+
+Custom Level example use-cases:
+
+- I have existing roles that I would like to leverage instead of / in addition
+  to using Guardrails' standard roles/groups
+- I want to manage my project at the sub-project level with custom roles
+- I don’t want to use Guardrails for authorization at all; I will manage GCP users,
+  roles, groups, and policies
+
+The Custom Levels policy allow you to map your existing IAM roles to Guardrails console
+users to provide them access to GCP. The custom roles will appear in the Guardrails Grant Permissions dialog box. They
+are named **{Provider}/Role/{RoleName}**, for example **GCP/Role/NetworksAdminRole**
+
+Custom levels can be specified via the
+`GCP > Permissions > Levels > Custom Levels [Project]` policies.