本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在 GitHub 工作中使用 AWS Secrets Manager 秘密
<a name="retrieving-secrets_github"></a>

要在 GitHub 作业中使用密钥，您可以使用 GitHub 操作从 AWS Secrets Manager 中检索密钥并将其作为屏蔽的[环境变量](https://docs.github.com/en/actions/learn-github-actions/environment-variables)添加到 GitHub 工作流程中。有关 GitHub 操作的更多信息，请参阅[了解*GitHub 文档*中的 GitHub 操作](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions)。

当你向 GitHub 环境中添加密钥时，该密钥可用于 GitHub 工作中的所有其他步骤。按照操作[安全强化中的指导进行 GitHub 操作](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)，以帮助防止环境中的密钥被滥用。

您可以将密钥值中的整个字符串设置为环境变量值，或者如果字符串为 JSON，则可以解析 JSON，以为每个 JSON 键值对设置单独的环境变量。如果密钥值是二进制，则操作会将密钥值转换为字符串。

若要查看从密钥创建的环境变量，请启用调试日志记录。有关更多信息，请参阅*GitHub 文档*中的[启用调试日志记录](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging)。

要使用根据您的密钥创建的环境变量，请参阅*GitHub 文档*中的[环境变量](https://docs.github.com/en/actions/learn-github-actions/environment-variables)。

## 先决条件
<a name="retrieving-secrets_github_prereq"></a>

要使用此操作，您首先需要配置 AWS 凭证，然后使用`configure-aws-credentials`步骤 AWS 区域 在您的 GitHub 环境中进行设置。按照[配置 AWS 凭证操作中的说明进行 GitHub 操作，](https://github.com/aws-actions/configure-aws-credentials)以便**使用 GitHub OIDC 提供程序直接担任角色**。这让您能够使用短期凭证，避免在 Secrets Manager 之外存储额外的访问密钥。

操作承担的 IAM 角色必须具有下列权限：
+ 您要检索的密钥的 `GetSecretValue` 权限。
+ 所有密钥的 `ListSecrets` 权限。
+ （可选）`Decrypt`上 KMS key 是否使用加密密钥 客户托管式密钥。

有关更多信息，请参阅 [的身份验证和访问控制 AWS Secrets Manager](auth-and-access.md)。

## 用法
<a name="retrieving-secrets_github_usage"></a>

若要使用该操作，请在工作流程中添加一个使用以下语法的步骤。

```
- name: Step name
  uses: aws-actions/aws-secretsmanager-get-secrets@v2
  with:
    secret-ids: |
      secretId1
      ENV_VAR_NAME, secretId2
    name-transformation: (Optional) uppercase|lowercase|none
    parse-json-secrets: (Optional) true|false
```参数

`secret-ids`  
密钥 ARN、名称和名称前缀。  
若要设置环境变量名称，请在密钥 ID 前输入该名称，然后输入逗号。例如，`ENV_VAR_1, secretId` 从密钥 `secretId` 中创建名为 **ENV\$1VAR\$11** 的环境变量。环境变量的名称可以包含小写字母、数字和下划线。  
若要使用前缀，请输入至少三个字符，然后输入星号。例如，`dev*` 匹配名称以 **dev** 开头的所有密钥。最多可以检索 100 个匹配密钥。如果您设置了变量名称，并且前缀与多个密钥匹配，则操作将失败。

`name-transformation`  
默认情况下，该步骤从密钥名称创建每个环境变量名称，并转换为仅包含大写字母、数字和下划线，防止名称以数字开头。对于名称中的字母，您可以通过 `lowercase` 将步骤配置为使用小写字母，或者通过 `none` 配置为不改变字母的大小写。默认值为 `uppercase`。

`parse-json-secrets`  
（可选）默认情况下，该操作将环境变量值设置为密钥值中的整个 JSON 字符串。将 `parse-json-secrets` 设置为 `true`，以为 JSON 中的每个键值对创建环境变量。  
请注意，如果 JSON 使用区分大小写的密钥（例如“name”和“Name”），则该操作将出现重复的名称冲突。在这种情况下，请将 `parse-json-secrets` 设置为 `false` 并单独解析 JSON 密钥值。

## 环境变量命名
<a name="retrieving-secrets_github_alias"></a>

操作创建的环境变量的名称与它们来源的密钥相同。环境变量的命名要求比密钥的命名要求更严格，因此操作会转换密钥名称，以满足这些要求。例如，该操作将把小写字母转换为大写字母。如果解析密钥的 JSON，则环境变量名称将同时包含密钥名称和 JSON 键名称，例如 `MYSECRET_KEYNAME`。您可以将操作配置为不转换小写字母。

如果两个环境变量具有相同的名称，则操作将失败。在这种情况下，您必须将要用于环境变量的名称指定为*别名*。

名称可能冲突的示例：
+ 名为 “” MySecret 的密钥和名为 “mysecret” 的密钥都将成为名为 “MYSECRET” 的环境变量。
+ 名为“Secret\$1keyname”的密钥以及名为“Secret”且具有“keyname”键的 JSON 解析密钥都将成为名为“SECRET\$1KEYNAME”的环境变量。

您可以通过指定*别名*来设置环境变量名称，如以下示例所示，它会创建一个名为 `ENV_VAR_NAME` 的变量。

```
secret-ids: |
  ENV_VAR_NAME, secretId2
```

**空白别名**
+ 如果您设置 `parse-json-secrets: true` 并输入空白别名，后跟逗号，然后是密钥 ID，则操作会将环境变量命名为与解析后的 JSON 键相同。变量名称不包含密钥名称。

  如果密钥不包含有效的 JSON，则操作会创建一个环境变量并将其命名为与密钥名称相同。
+ 如果您设置 `parse-json-secrets: false` 并输入空白别名，后跟逗号，然后是密钥 ID，则操作将命名环境变量，就好像您没有指定别名一样。

以下示例显示了一个空白别名。

```
,secret2
```

## 示例
<a name="retrieving-secrets_github_examples"></a>

**Example 1 按名称和 ARN 获取密钥**  
下列示例为按名称和 ARN 标识的密钥创建环境变量。  

```
- name: Get secrets by name and by ARN
  uses: aws-actions/aws-secretsmanager-get-secrets@v2
  with:
    secret-ids: |
      exampleSecretName
      arn:aws:secretsmanager:us-east-2:123456789012:secret:test1-a1b2c3
      0/test/secret
      /prod/example/secret
      SECRET_ALIAS_1,test/secret
      SECRET_ALIAS_2,arn:aws:secretsmanager:us-east-2:123456789012:secret:test2-a1b2c3
      ,secret2
```
已创建的环境变量：  

```
EXAMPLESECRETNAME: secretValue1
TEST1: secretValue2
_0_TEST_SECRET: secretValue3
_PROD_EXAMPLE_SECRET: secretValue4
SECRET_ALIAS_1: secretValue5
SECRET_ALIAS_2: secretValue6
SECRET2: secretValue7
```

**Example 2 获取所有以前缀开头的密钥**  
以下示例为所有名称以开头的密钥创建环境变量*beta*。  

```
- name: Get Secret Names by Prefix
  uses: 2
  with:
    secret-ids: |
      beta*    # Retrieves all secrets that start with 'beta'
```
已创建的环境变量：  

```
BETASECRETNAME: secretValue1
BETATEST: secretValue2
BETA_NEWSECRET: secretValue3
```

**Example 3 在密钥中解析 JSON**  
下列示例通过解析密钥中的 JSON 来创建环境变量。  

```
- name: Get Secrets by Name and by ARN
  uses: aws-actions/aws-secretsmanager-get-secrets@v2
  with:
    secret-ids: |
      test/secret
      ,secret2
    parse-json-secrets: true
```
密钥 `test/secret` 具有下列密钥值。  

```
{
  "api_user": "user",
  "api_key": "key",
  "config": {
    "active": "true"
  }
}
```
密钥 `secret2` 具有下列密钥值。  

```
{
  "myusername": "alejandro_rosalez",
  "mypassword": "EXAMPLE_PASSWORD"
}
```
已创建的环境变量：  

```
TEST_SECRET_API_USER: "user"
TEST_SECRET_API_KEY: "key"
TEST_SECRET_CONFIG_ACTIVE: "true"
MYUSERNAME: "alejandro_rosalez"
MYPASSWORD: "EXAMPLE_PASSWORD"
```

**Example 4 对环境变量名称使用小写字母**  
以下示例将创建一个具有小写名称的环境变量。  

```
- name: Get secrets
  uses: aws-actions/aws-secretsmanager-get-secrets@v2
  with:
    secret-ids: exampleSecretName
    name-transformation: lowercase
```
已创建的环境变量：  

```
examplesecretname: secretValue
```