mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-03 20:17:59 +00:00
docs: sync/github-apps (#25569)
This commit is contained in:
Raymond Ho
@@ -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
|
||||
```
|
||||
|
||||
@@ -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 \
|
||||
@@ -149,6 +155,80 @@ unintended disclosure of secrets in any GitHub Action outputs. The following sni
|
||||
|
||||
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>
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user