chore(gh-integration): Updating Github integration plugin docs

content/en/includes/plugins/github/accounts-config-example.md

@@ -14,17 +14,20 @@ github:
         defaultBranch: master
         githubAppId: 9753
         githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
+        permissions: []
       - name: SecondAppRepo
         organization:  company-public
         repository: second-app-repo
         defaultBranch: main
         githubAppId: 9753
         githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
+        permissions: []
       - name: CompanyPrivateOrgAllRepos
         organization: company-private
         orgWideInstallation: true
         includePublicRepositories: false
         defaultBranch: main
         githubAppId: 1357
         githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-1357-privatekey
+        permissions: []
 ```

content/en/includes/plugins/github/install-reqs.md

@@ -1,2 +1,2 @@
-* You have read the GitHub Integration Plugin [overview]({{< ref "plugins/github-integration/_index.md" >}}).
+* You have read the GitHub Integration Plugin [overview]({{< ref "plugins/github-integration/overview.md" >}}).
 * You are familiar with [GitHub Apps](https://docs.github.com/en/apps/overview).

content/en/includes/plugins/github/plugin-config.md

@@ -13,6 +13,7 @@
   defaultBranch: <default-github-branch>
   githubAppId: <github-app-id>
   githubAppPrivateKey: <github-app-private-key>
+  permissions: []
 ```
 
 All fields are required.
@@ -35,6 +36,7 @@ All fields are required.
   defaultBranch: <default-github-branch>
   githubAppId: <github-app-id>
   githubAppPrivateKey: <github-app-private-key>
+  permissions: []
 ```
 
 All fields are required.

content/en/plugins/github-integration/_index.md

@@ -1,91 +1,8 @@
 ---
 title: GitHub Integration Plugin for Spinnaker
 linkTitle: GitHub Integration
-no_list: true
 description: >
   Armory's GitHub Integration plugin for Spinnaker streamlines integration with GitHub Actions, filling the native support gap. The plugin enables easy triggering of GitHub Actions workflows, dynamic control of Spinnaker pipelines based on workflow outcomes, and seamless synchronization of GitHub Deployment statuses with Spinnaker pipeline conclusions.
 ---
 
 ![Proprietary](/images/proprietary.svg) ![Beta](/images/beta.svg)
-
-## GitHub Integration Plugin features
-
-The GitHub Integration Plugin provides the following GitHub integration features:
-
-- Trigger a GitHub Actions workflow from a Spinnaker pipeline using **workflow_dispatch** or **repository_dispatch** events
-- Trigger a Spinnaker pipeline automatically when a GitHub workflow finishes successfully
-- Trigger a Spinnaker pipeline when GitHub creates a new GitHub Deployment
-- Monitor a GitHub workflow and finish pipeline execution based on the GitHub workflow result
-- Update GitHub deployment status based on Spinnaker pipeline outcome
-- View GitHub Action Logs in Spinnaker -- there is no need to navigate to GitHub to view the logs
-
-The GitHub Integration plugin uses [GitHub Apps](https://docs.github.com/en/apps/overview) to integrate with GitHub. GitHup Apps provide webhooks and narrow, specific permissions. You can install a GitHub App  that gives the GitHub Integration plugin access to all the repos in your GitHub organization, or you can install a Github App that gives the GitHub Integration plugin access to specific repos. You can install as many GitHub Apps as your use case requires.
-
-## How the plugin works with GitHub
-
-```mermaid
-graph TD
-	Orca -->|Workflow Trigger| Igor
-	Gate --> |Trigger based on Deployment event|Echo
-	Igor -->|Trigger/Monitor triggered workflows| GitHub
-	Echo -->|Pipeline triggers|Orca
-	Orca -->|Pipeline notifications|Echo
-	GitHub --> |Deployment event| Gate
-	Echo --> |Notifications|GitHub
-```
-
-For example, the plugin processes a GitHub Deployment event like this:
-
-```mermaid
-sequenceDiagram
-participant ghActions as "GitHub Workflow job"
-participant gh as "GitHub"
-participant gate as "Gate"
-participant echo as "Echo"
-participant orca as "Orca"
-
-ghActions ->> gh: "Create Deployment"
-gh ->> ghActions: "Deployment created"
-gh ->> gate: "Deployment Event"
-gate ->> echo: "Deployment trigger event"
-echo ->> orca: "Trigger pipelines matching the Trigger event"
-orca ->> gh: "Deployment status update: in_progress, success, failure, or error"
-```
-
-## Compatibility matrix
-
-{{< include "plugins/github/compat-matrix.md" >}}
-
-## Installation paths
-
-{{% cardpane %}}
-{{% card header="Armory CD<br>Armory Operator" %}}
-Use a Kustomize patch to install the plugin.
-
-1. Create a GitHub App and install it in your repo or organization.
-1. Configure the plugin with your GitHub repo(s) and/or organization(s).
-1. Install the plugin using the Armory Operator.
-
-[Instructions]({{< ref "plugins/github-integration/install/armory-cd" >}})
-{{% /card %}}
-
-{{% card header="Spinnaker<br>Spinnaker Operator" %}}
-Use a Kustomize patch to install the plugin.
-
-1. Create a GitHub App and install it in your repo.
-1. Configure the plugin with your GitHub repo(s) and/or organization(s).
-1. Install the plugin using the Spinnaker Operator.
-
-[Instructions]({{< ref "plugins/github-integration/install/spinnaker-operator" >}})
-{{% /card %}}
-
-{{% card header="Spinnaker<br>Halyard" %}}
-Use Spinnaker local config files to install the plugin.
-
-1. Create a GitHub App and install it in your repo.
-1. Configure the plugin with your GitHub repo(s) and/or organization(s).
-1. Install the plugin in local config files and apply those changes using Halyard.
-
-[Instructions]({{< ref "plugins/github-integration/install/spinnaker-halyard" >}})
-{{% /card %}}
-{{% /cardpane %}}

content/en/plugins/github-integration/authz.md

@@ -0,0 +1,113 @@
+---
+title: Enable and Configure AuthZ in the GitHub Integration Plugin
+linkTitle: Enable AuthZ
+weight: 10
+description: >
+  Learn how to enable and configure AuthZ support for GitHub App accounts.
+---
+
+
+![Proprietary](/images/proprietary.svg) ![Beta](/images/beta.svg)
+
+## AuthZ plugin overview
+
+This feature enables AuthZ support for GitHub App accounts and provides these features:
+
+* **Compliance and Security**
+
+   Authz for GitHub App accounts allows you to enforce access controls on a per-account basis, securing access to specific repositories and/or GitHub organizations to only authorized groups/teams.
+
+* **Granular Control**
+
+   Authz for GitHub App accounts provides granular control over who can perform actions within each account. This fine-grained permission control is crucial for maintaining a least privilege principle, where users have only the necessary access to perform their tasks, reducing the overall security surface.
+
+* **Scalability**
+
+   Authz for GitHub App accounts scales effectively as the number of accounts grows. This scalability is essential for organizations managing diverse and expanding infrastructure, ensuring that access controls remain manageable and effective.
+
+Fiat is the Spinnaker microservice responsible for authorization (authz) for the other Spinnaker services. 
+It is not enabled by default, so users are able to perform any action in Spinnaker. When enabled, Fiat checks the user's permissions before allowing the action to proceed.
+
+
+### How this feature works
+
+The GitHub Integration plugin supports Fiat authz for GitHub App accounts configured to determine whether a role or group can perform the following actions:
+
+- `READ`: A user can view the GitHub App account's configuration and/or use it as a trigger source.
+- `WRITE`: A user can use the GitHub App account as the target account for the GitHub integration plugin stages.
+
+
+```mermaid
+sequenceDiagram
+	participant user as User
+	participant gate as Gate
+	participant orca as Orca
+	participant igor as Igor
+	participant fiat as Fiat
+	participant gh as GitHub
+
+user ->> gate: Start execution for pipeline (includes plugin stage)
+gate ->> orca: Submit execution for pipeline (includes plugin stage)
+orca ->> igor: Submit the task operations of plugin stage
+igor ->> fiat: Check hasPermissions
+alt Unauthorized
+	fiat ->> igor: hasPermissions=false 
+	igor ->> orca: Fail with Forbidden
+	orca ->> gate: TERMINAL
+else Authorized
+	fiat ->> igor: hasPermissions=true
+	igor ->> orca: IN_PROGRESS
+	igor ->> gh: API calls
+	orca ->> gate: IN_PROGRESS
+end
+```
+
+### {{% heading "prereq" %}}
+
+- You are familiar with how Spinnaker's [AuthZ]({{< ref "continuous-deployment/overview/fiat-permissions-overview" >}}) works.
+- You have read the GitHub Integration Plugin [overview]({{< ref "plugins/github-integration/overview.md" >}}).
+- You have enabled Fiat in your Spinnaker or Armory CD instance integrated with an external identity provider (IDP).
+
+### How to enable AuthZ support
+
+You can enable AuthZ support per GitHub App account by setting the `permissions` block in the `github-integration-plugin.yml` file. For example:
+
+{{< highlight yaml "linenos=table,hl_lines=10-17 32-37" >}}
+github:
+  plugin:
+    accounts:
+      - name: FirstAppRepo
+        organization:  company-public
+        repository: first-app-repo
+        defaultBranch: master
+        githubAppId: 9753
+        githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
+        permissions:
+          READ: 
+            - "read-only-role"
+            - "dev-role"
+            - "ops-role"
+          EXECUTE:
+            - "dev-role"
+            - "ops-role"
+      - name: SecondAppRepo
+        organization:  company-public
+        repository: second-app-repo
+        defaultBranch: main
+        githubAppId: 9753
+        githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-9753-privatekey
+        permissions: []
+      - name: CompanyPrivateOrgAllRepos
+        organization: company-private
+        orgWideInstallation: true
+        includePublicRepositories: false
+        defaultBranch: main
+        githubAppId: 1357
+        githubAppPrivateKey: encrypted:k8s!n:spin-secrets!k:github-app-1357-privatekey
+        permissions:
+          READ:
+            - "read-only-role"
+            - "ops-role"
+          EXECUTE:
+            - "ops-role"
+{{< /highlight >}}

content/en/plugins/github-integration/commit-status-notifications.md

@@ -0,0 +1,82 @@
+---
+title: Enable GitHub Commit Status Echo notifications
+linkTitle: Enable Notifications
+weight: 10
+description: >
+  Learn how to enable an enhanced Echo notification type which can be configured to send notifications for pipelines and/or stages statuses with custom context and description linking to the Spinnaker UI as a target URL. 
+---
+
+![Proprietary](/images/proprietary.svg) ![Beta](/images/beta.svg)
+
+
+## Configure GitHub Commit Status Echo notifications
+
+Echo is the microservice in Spinnaker which (among other functionalities) manages notifications for Spinnaker pipelines and stages.
+
+Using the GitHub Integration plugin you can configure Echo to create [GitHub Commit Statuses](https://docs.github.com/en/rest/commits/statuses?apiVersion=2022-11-28#create-a-commit-status)
+in a repository by authenticating using the GitHub App accounts configured in the plugin.
+
+By using the GitHub Integration's plugin GitHub Commit Status notifications, you can link the deployment pipeline statuses to GitHub status checks. This feature provides clear and immediate feedback to developers about the deployment pipeline status. 
+
+## How this feature works
+
+GitHub Integration plugin offers an enhanced Echo notification type which can be configured to send notifications
+for pipelines and/or stages statuses with custom context and description linking to the Spinnaker UI as a target URL.
+
+## How to enable
+
+GitHub Commit Status notifications can be enabled per GitHub App account by enabling the feature in Echo and Deck services in the `github-integration-plugin.yml` file.
+
+{{< highlight yaml "linenos=table,hl_lines=7-8 14-15" >}}
+spec:
+  spinnakerConfig:
+    profiles:
+      spinnaker:
+        github:
+          plugin:
+            github-status:
+              enabled: true
+            accounts: []
+      deck:
+        settings-local.js: |
+          window.spinnakerSettings = {
+            ... (content omitted for brevity)
+            feature.githubIntegrationFlags = {
+              githubStatus: true
+            };  
+            ... (content omitted for brevity)
+          }
+{{< /highlight >}}
+
+## Migrating from Echo's default implementation
+
+Migrating from the default implementation to the GitHub Integration plugin's implementation does not require any changes in your pipelines. The GitHub Integration plugin's implementation is used automatically when the feature is enabled in Echo and Deck services and the default implementation is disabled. To ensure a smooth migration, follow these steps:
+
+
+1. Disable the default implementation by disabling the `github-status` feature in Echo and Deck services
+
+   {{< highlight yaml "linenos=table,hl_lines=6 13" >}}
+   spec:
+     spinnakerConfig:
+       profiles:
+         echo:
+           github-status:
+             enabled: false
+             token: <PAT>
+             endpoint: https://api.github.com
+         deck:
+           settings-local.js: |
+             window.spinnakerSettings = {
+               ... (content omitted for brevity)
+               notifications.githubStatus.enabled = false;
+               ... (content omitted for brevity)
+             }
+   {{< /highlight >}}
+
+1. Enable the GitHub Integration plugin. See the [Get Started]({{< ref "plugins/github-integration/install/_index.md" >}}) section for instructions.
+
+1. Ensure that you have configured the appropriate GitHub App accounts for every GitHub organization that you want to send notifications to.
+
+1. Verify that the Deck UI is showing the plugin's Commit Status notification type in the notification settings for 
+your pipelines and the Commit Statuses are being created in GitHub.
+

content/en/plugins/github-integration/install/_index.md

@@ -1,7 +1,39 @@
 ---
 title: Get Started with the GitHub Integration Plugin
 linkTitle: Get Started
-weight: 1
+weight: 2
 description: >
-   In this section, learn how to install the GitHub Integration Plugin for Spinnaker and Armory Continuous Deployment. 
+   In this section, learn how to install the GitHub Integration Plugin for Spinnaker and Armory Continuous Deployment. Use the Armory Operator with Armory CD. Spinnaker users can install the plugin using the Spinnaker Operator or Halyard.
 ---
+
+{{% cardpane %}}
+{{% card header="Armory CD<br>Armory Operator" %}}
+Use a Kustomize patch to install the plugin.
+
+1. Create a GitHub App and install it in your repo or organization.
+1. Configure the plugin with your GitHub repo(s) and/or organization(s).
+1. Install the plugin using the Armory Operator.
+
+[Instructions]({{< ref "plugins/github-integration/install/armory-cd" >}})
+{{% /card %}}
+
+{{% card header="Spinnaker<br>Spinnaker Operator" %}}
+Use a Kustomize patch to install the plugin.
+
+1. Create a GitHub App and install it in your repo.
+1. Configure the plugin with your GitHub repo(s) and/or organization(s).
+1. Install the plugin using the Spinnaker Operator.
+
+[Instructions]({{< ref "plugins/github-integration/install/spinnaker-operator" >}})
+{{% /card %}}
+
+{{% card header="Spinnaker<br>Halyard" %}}
+Use Spinnaker local config files to install the plugin.
+
+1. Create a GitHub App and install it in your repo.
+1. Configure the plugin with your GitHub repo(s) and/or organization(s).
+1. Install the plugin in local config files and apply those changes using Halyard.
+
+[Instructions]({{< ref "plugins/github-integration/install/spinnaker-halyard" >}})
+{{% /card %}}
+{{% /cardpane %}}

content/en/plugins/github-integration/install/armory-cd.md

@@ -40,7 +40,7 @@
 
 {{% alert title="Conflict with Armory CDSH v2.30.x" color="warning" %}}
 
-[Known issue]({{< ref "plugins/github-integration/release-notes#armoryheader-plugin-conflict" >}}): The GitHub Integration plugin conflicts with the Armory.Header plugin version included in CDSH v2.30.x. You must install version 0.2.0 of the Armory.Header plugin. 
+[Known issue]({{< ref "plugins/github-integration/release-notes#armoryheader-plugin-conflict" >}}): The GitHub Integration plugin conflicts with the Armory.Header plugin version included in Armory CD v2.30.x. You must install version 0.2.0 of the Armory.Header plugin. 
 <details><summary>Show me how</summary>
 {{< include "plugins/github/armory-header-plugin.md" >}}
 </details>