Backport of Docs/vault 23837/sync doc update into release/1.16.x (#26058)

* Docs/vault 23837/sync doc update (#25433)

* + documented the new sync API options

* * cherry-pick
* address review comments

* move statuses into a table for consistency
* fix merge conflicts

---------

Co-authored-by: Max Coulombe <[email protected]>
Co-authored-by: mickael-hc <[email protected]>
Co-authored-by: maxcoulombe <[email protected]>

Author: 3 people

website/content/api-docs/system/secrets-sync.mdx

@@ -424,7 +424,16 @@ This endpoint creates a destination to synchronize action secrets with a GitHub
 
 - `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
 
-- `access_token` `(string: <required>)` - Fine-grained or personal access token.
+- `access_token` `(string: <optional>)` - Fine-grained or personal access token.
+  Use `access_token` as an alternative to authenticating with a GitHub app.
+
+- `app_name` `(string: <optional>)` - The name of a GitHub App configured in Vault to use for
+  authentication. Use `app_name` and `installation_id` as an alternative to
+  authenticating with an access token.
+
+  - `installation_id` `(string: <optional>)` - The installation ID of the GitHub
+  app to use for authentication. Required when using `app_name` for
+  authentication.
 
 - `repository_owner` `(string: <required>)` - GitHub organization or username that owns the repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the owner is hashicorp.
 
@@ -826,3 +835,127 @@ $ curl \
     "auth": null
 }
 ```
+
+## Configure a custom GitHub app
+
+Use the `POST` operation with `sys/sync/github-apps` endpoint to configure a
+custom GitHub application for syncing secrets with GitHub repositories.
+
+
+| Method | Path                         |
+|:-------|:-----------------------------|
+| `POST` | `sys/sync/github-apps/:name` |
+
+
+### Parameters
+
+- `name` `(string: <required>)` - Specifies a custom name for the GitHub
+application that is used when configuring the destination. Although this can be any name, we recommend using the same app name configured in GitHub.
+
+- `app_id` `(string: <required>)` - Specifies the GitHub application ID, provided by GitHub.
+
+- `private_key` `(string: <required>)` - Specifies the private key used to authenticate with the GitHub application.
+
+### Sample payload
+```json
+{
+    "app_id": "true",
+    "private_key":  "<PRIVATE KEY PEM>"
+}
+```
+
+### Sample requests
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    --data @payload.json
+    http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app
+```
+
+
+### Sample response
+
+```json
+{
+    "request_id": "uuid",
+    "data": {
+        "app_id": 123456,
+        "fingerprint": "<fingerprint>",
+        "name": "my-custom-app",
+        "private_key": "*****"
+    },
+    "mount_type": "system"
+}
+```
+
+## Read custom GitHub app
+
+Use the `GET` operation with `sys/sync/github-apps` to view details about the
+configured GitHub application.
+
+
+| Method | Path                         |
+|:-------|:-----------------------------|
+| `GET`  | `sys/sync/github-apps/:name` |
+
+
+### Parameters
+
+- `name` `(string: <required>)` - Specifies a custom name for the GitHub application.
+
+
+### Sample requests
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request GET \
+    http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app
+```
+
+
+### Sample response
+
+```json
+{
+    "request_id": "uuid",
+    "data": {
+        "app_id": 123456,
+        "fingerprint": "<fingerprint>",
+        "name": "my-custom-app",
+        "private_key": "*****"
+    },
+    "mount_type": "system"
+}
+```
+
+## Delete custom GitHub app
+
+Use the `DELETE` operation with `sys/sync/github-apps` to delete a configured
+GitHub application.
+
+You cannot delete applications with active authentication destination
+references. Deleting an application configuration **does not** delete the GitHub
+application from GitHub.
+
+
+| Method   | Path                         |
+|:---------|:-----------------------------|
+| `DELETE` | `sys/sync/github-apps/:name` |
+
+
+### Parameters
+
+- `name` `(string: <required>)` - Specifies a custom name for the GitHub application.
+
+
+### Sample requests
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request DELETE \
+    http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app
+```

website/content/docs/sync/github.mdx

@@ -12,17 +12,23 @@ to connect directly with Vault. This guide walks you through the configuration p
 
 Prerequisites:
 * Ability to read or create KVv2 secrets
-* Ability to create GitHub fine-grained or personal tokens with access to modify repository secrets
+* Ability to create GitHub fine-grained or personal tokens (or a GitHub application) with access to modify repository secrets
 * Ability to create sync destinations and associations on your Vault server
 
 ## Setup
 
-1. To get started with syncing Vault secrets to your GitHub repository, you will need an
+1. To get started with syncing Vault secrets to your GitHub repository, you will need a configured [GitHub application](#github-application) or an
   [access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
   which has access to the repository you want to manage secrets for and write permissions on the repository's actions secrets.
   In the list of GitHub permissions, this is simply called "Secrets". Choosing this will automatically include read-only Metadata.
 
-1. Configure a sync destination with the access token created in the previous step.
+<Warning title="Pitfalls of using an access token">
+  Access tokens are tied to a user account and can be revoked at any time, causing disruptions to the sync process.
+  GitHub applications are long-lived and do not expire. Using a GitHub application for authentication is preferred over using a personal access token.
+</Warning>
+
+
+If you decide to go with an access token, here's how you can configure a sync destination:
 
   ```shell-session
   $ vault write sys/sync/destinations/gh/my-dest \
@@ -122,12 +128,13 @@ or the association in Vault will delete the secret in GitHub as well.
 <Note>
 
 GitHub only supports single value secrets, so KVv2 secrets from Vault will be stored as a JSON string.
-In the example above, the value for secret "my-secret" will be synced to GitHub as the JSON string `{"foo":"bar"}`.
+In the example above, the value for secret "my-secret" will be synced to GitHub as the JSON string `{"foo":"bar"}` if the
+destination is configured to use the `secret-path` [granularity level](/vault/docs/sync#granularity).
 
 </Note>
 
-It is strongly advised to mask individual values for each sub-key to prevent the unintended disclosure of secrets
-in any GitHub Action outputs. The following snippet illustrates how to mask each secret values:
+If using the secret-path granularity, it is strongly advised to mask individual values for each sub-key to prevent the
+unintended disclosure of secrets in any GitHub Action outputs. The following snippet illustrates how to mask each secret values:
 
   ```yaml
   name: Mask synced secret values
@@ -146,6 +153,91 @@ in any GitHub Action outputs. The following snippet illustrates how to mask each
             done
   ```
 
+If the GitHub destination uses the default `secret-key` granularity, the values are masked by GitHub automatically.
+
+## GitHub application
+
+Instead of authenticating with a personal access token, you can choose to
+authenticate with a
+[custom GitHub application](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
+
+Start by following the GitHub instructions for
+[installing a GitHub app](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app).
+to install your GitHub application on a specified repository and note the
+assigned installation ID.
+
+<Tip title="Your installation ID is in the app URL">
+
+  You can find your assigned installation ID in the URL path parameter:
+  `https://github.com/settings/installations/<INSTALLATION_ID>`
+
+</Tip>
+
+Then add your GitHub application to your Vault instance.
+
+To use your GitHub application with Vault:
+
+- the application must have permission to read and write secrets.
+- you must generate a private key for the application on GitHub.
+- the application must be installed on the repository you want to sync secrets with.
+- you must know the application ID assigned by GitHub.
+- you must know the installation ID assigned by GitHub.
+
+Callback, redirect URLs, and webhooks are not required at this time.
+
+To configure the application in Vault, use `vault write` with the
+`sys/sync/github-apps` endpoint to assign a unique name and set the relevant
+information:
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ vault write sys/sync/github-apps/<APP_NAME> \
+  app_id=<APP_ID> \
+  private_key=<PATH_TO_PRIVATE_KEY>
+
+Key            Value
+---            -----
+app_id         <app-id>
+fingerprint    <fingerprint>
+name           <app-name>
+private_key    *****
+```
+</CodeBlockConfig>
+
+<Tip title="Fingerprint verification">
+
+Vault returns the fingerprint of the private_key provided to ensure that the
+correct private key was configured and that it was not tampered with along the way.
+You can compare the fingerprint to the one provided by GitHub.
+For more information, see [Verifying private keys](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#verifying-private-keys).
+
+</Tip>
+
+
+Next, use `vault write` with the `sys/sync/destinations/gh` endpoint to
+configure a GitHub destination that references your new GitHub application:
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ vault write sys/sync/destinations/gh/<DESTINATION_NAME> \
+installation_id=<INSTALLATION_ID>                         \
+repository_owner=<GITHUB_USER>                            \
+repository_name=<MY_REPO_NAME>                            \
+app_name=<APP_NAME>
+
+Key                   Value
+---                   -----
+connection_details    map[app_config:map[app_name:<app-name>] installation_id:<installation-id> repository_name:<repo-name> repository_owner:<repo-owner>]
+name                  my-dest
+options               map[custom_tags:map[] granularity_level:secret-key secret_name_template:VAULT_{{ .MountAccessor | uppercase }}_{{ .SecretPath | uppercase }}_{{ .SecretKey | uppercase }}]
+type                  gh
+```
+</CodeBlockConfig>
+
+You can now [use your GitHub application to sync secrets with your GitHub repository](#usage).
+
 ## API
 
 Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.