create-secret

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Secret Skill

创建Secret Skill

Generate Harness Secret definitions and manage secrets via MCP v2 tools.

通过MCP v2工具生成Harness Secret定义并管理密钥。

MCP v2 Tools Used

使用的MCP v2工具

Tool	Resource Type	Purpose
`harness_list`	`secret`	List existing secrets
`harness_get`	`secret`	Get secret metadata (not the value)
`harness_create`	`secret`	Create a new secret
`harness_update`	`secret`	Update secret metadata or value
`harness_delete`	`secret`	Delete a secret
`harness_describe`	`secret`	Discover secret resource schema

工具	资源类型	用途
`harness_list`	`secret`	列出现有密钥
`harness_get`	`secret`	获取密钥元数据（不包含密钥值）
`harness_create`	`secret`	创建新密钥
`harness_update`	`secret`	更新密钥元数据或值
`harness_delete`	`secret`	删除密钥
`harness_describe`	`secret`	发现密钥资源架构

Secret Types

密钥类型

SecretText

Stores text-based secrets: passwords, API tokens, connection strings.

yaml

secret:
  identifier: my_api_key
  name: My API Key
  description: API key for external service
  type: SecretText
  spec:
    secretManagerIdentifier: harnessSecretManager
    valueType: Inline
    value: <secret_value>

For other secret types (SecretFile, SSHKey with KeyReference/KeyPath/Password, WinRmCredentials with NTLM/Kerberos) and secret manager configuration, consult references/secret-types.md.

存储基于文本的密钥：密码、API令牌、连接字符串。

yaml

secret:
  identifier: my_api_key
  name: My API Key
  description: API key for external service
  type: SecretText
  spec:
    secretManagerIdentifier: harnessSecretManager
    valueType: Inline
    value: <secret_value>

其他密钥类型（SecretFile、带KeyReference/KeyPath/Password的SSHKey、带NTLM/Kerberos的WinRmCredentials）以及密钥管理器配置，请参考references/secret-types.md。

Secret Scopes

密钥范围

Scope	Visibility	MCP Parameters
Project	Only within the project	`org_id` + `project_id`
Organization	All projects in the org	`org_id` only
Account	All orgs and projects	Neither org_id nor project_id

范围	可见性	MCP参数
项目	仅在项目内可见	`org_id` + `project_id`
组织	组织内所有项目可见	仅 `org_id`
账号	所有组织和项目可见	无需org_id或project_id

Instructions

操作步骤

Step 1: Determine Requirements

步骤1：确定需求

Secret type: SecretText, SecretFile, SSHKey, or WinRmCredentials
Secret manager: Harness built-in or external
Scope: project, org, or account
Tags and description for organization

密钥类型：SecretText、SecretFile、SSHKey或WinRmCredentials
密钥管理器：Harness内置或外部管理器
范围：项目、组织或账号
用于分类的标签和描述

Step 2: Check for Existing Secrets

步骤2：检查现有密钥

harness_list(
  resource_type="secret",
  org_id="<org>",
  project_id="<project>",
  search_term="<keyword>"
)

harness_list(
  resource_type="secret",
  org_id="<org>",
  project_id="<project>",
  search_term="<keyword>"
)

Step 3: Create the Secret

步骤3：创建密钥

harness_create(
  resource_type="secret",
  org_id="<org>",
  project_id="<project>",
  body={
    "secret": {
      "identifier": "my_api_key",
      "name": "My API Key",
      "type": "SecretText",
      "spec": {
        "secret_manager_identifier": "harnessSecretManager",
        "value_type": "Inline",
        "value": "<value>"
      }
    }
  }
)

harness_create(
  resource_type="secret",
  org_id="<org>",
  project_id="<project>",
  body={
    "secret": {
      "identifier": "my_api_key",
      "name": "My API Key",
      "type": "SecretText",
      "spec": {
        "secret_manager_identifier": "harnessSecretManager",
        "value_type": "Inline",
        "value": "<value>"
      }
    }
  }
)

Step 4: Verify Creation

步骤4：验证创建结果

harness_get(
  resource_type="secret",
  resource_id="my_api_key",
  org_id="<org>",
  project_id="<project>"
)

harness_get(
  resource_type="secret",
  resource_id="my_api_key",
  org_id="<org>",
  project_id="<project>"
)

Referencing Secrets in Pipelines

在流水线中引用密钥

yaml

undefined

yaml

undefined

Project-level secret

项目级密钥

<+secrets.getValue("my_api_key")>

Org-level secret

组织级密钥

<+secrets.getValue("org.my_api_key")>

Account-level secret

账号级密钥

<+secrets.getValue("account.my_api_key")>


In connector configuration:

```yaml
connector:
  spec:
    authentication:
      spec:
        tokenRef: github_pat   # secret identifier

In service variables:

yaml

variables:
  - name: DB_PASSWORD
    type: Secret
    value: <+secrets.getValue("db_password")>

<+secrets.getValue("account.my_api_key")>


在连接器配置中：

```yaml
connector:
  spec:
    authentication:
      spec:
        tokenRef: github_pat   # secret identifier

在服务变量中：

yaml

variables:
  - name: DB_PASSWORD
    type: Secret
    value: <+secrets.getValue("db_password")>

Naming Conventions

命名规范

Secret Type	Pattern	Example
API Keys	`{service}_api_key`	`github_api_key`
Passwords	`{system}_password`	`prod_db_password`
Tokens	`{provider}_token`	`slack_token`
SSH Keys	`ssh_{purpose}`	`ssh_deploy_key`
Certificates	`{service}_cert`	`ssl_prod_cert`

Identifier must match:

^[a-zA-Z_][0-9a-zA-Z_]{0,127}$

密钥类型	格式	示例
API密钥	`{service}_api_key`	`github_api_key`
密码	`{system}_password`	`prod_db_password`
令牌	`{provider}_token`	`slack_token`
SSH密钥	`ssh_{purpose}`	`ssh_deploy_key`
证书	`{service}_cert`	`ssl_prod_cert`

标识符必须匹配正则：

^[a-zA-Z_][0-9a-zA-Z_]{0,127}$

Examples

示例

Create a GitHub PAT secret

创建GitHub PAT密钥

/create-secret
Create a SecretText for a GitHub personal access token at the project level
using the Harness built-in secret manager

/create-secret
Create a SecretText for a GitHub personal access token at the project level
using the Harness built-in secret manager

Create SSH credentials

创建SSH凭据

/create-secret
Create an SSH key secret for deploying to production servers as the "deploy" user

/create-secret
Create an SSH key secret for deploying to production servers as the "deploy" user

Create a Vault-referenced secret

创建Vault引用密钥

/create-secret
Create a secret that references the database password stored in HashiCorp Vault
at secret/data/production/database#password

/create-secret
Create a secret that references the database password stored in HashiCorp Vault
at secret/data/production/database#password

List secrets

列出密钥

/create-secret
Show me all secrets in the payments project

/create-secret
Show me all secrets in the payments project

Create WinRM credentials

创建WinRM凭据

/create-secret
Create WinRM NTLM credentials for the Windows deployment servers

/create-secret
Create WinRM NTLM credentials for the Windows deployment servers

Error Handling

错误处理

Error	Cause	Solution
Duplicate identifier	Secret with same ID exists	Use unique identifier or update existing
Secret manager not found	Invalid `secretManagerIdentifier`	Verify the secret manager connector exists
Encryption failed	Secret manager connectivity issue	Check delegate connectivity to secret manager
Invalid secret type	Unsupported type string	Use `SecretText` , `SecretFile` , `SSHKey` , or `WinRmCredentials`
Invalid valueType	Case mismatch	Use `Inline` or `Reference` (case-sensitive)

错误	原因	解决方案
标识符重复	存在相同ID的密钥	使用唯一标识符或更新现有密钥
密钥管理器未找到	`secretManagerIdentifier` 无效	验证密钥管理器连接器是否存在
加密失败	密钥管理器连接问题	检查Delegate与密钥管理器的连通性
无效密钥类型	使用了不支持的类型字符串	使用 `SecretText` 、 `SecretFile` 、 `SSHKey` 或 `WinRmCredentials`
无效valueType	大小写不匹配	使用 `Inline` 或 `Reference` （区分大小写）

Performance Notes

性能注意事项

Never include actual secret values in generated YAML. Use placeholder references only.
Verify the correct scope (account, org, project) before creating — secrets at the wrong scope will not be accessible.
Confirm the secret manager exists and is accessible before creating secrets.

切勿在生成的YAML中包含实际密钥值，仅使用占位符引用。
创建前确认正确的范围（账号、组织、项目）——错误范围的密钥将无法访问。
创建密钥前确认密钥管理器存在且可访问。

Troubleshooting

故障排除

Secret Not Accessible in Pipeline

流水线中无法访问密钥

Check scope -- project secrets need no prefix, org secrets need
```
org.
```
prefix, account secrets need
```
account.
```
prefix
Verify the pipeline's project has access to the secret's scope
Confirm the user/service account running the pipeline has
```
core_secret_view
```
permission

检查范围——项目级密钥无需前缀，组织级密钥需要
```
org.
```
前缀，账号级密钥需要
```
account.
```
前缀
验证流水线所在项目是否有权访问密钥的范围
确认运行流水线的用户/服务账号拥有
```
core_secret_view
```
权限

External Secret Manager Errors

外部密钥管理器错误

Verify the secret manager connector is healthy (
```
harness_get
```
on the connector)
For Vault: check the path format includes
```
#key
```
suffix for specific keys
For AWS SM: ensure IAM permissions allow
```
secretsmanager:GetSecretValue
```
Delegate must have network access to the external secret manager

验证密钥管理器连接器是否正常（对连接器执行
```
harness_get
```
）
对于Vault：检查路径格式是否包含
```
#key
```
后缀以指定具体密钥
对于AWS SM：确保IAM权限允许
```
secretsmanager:GetSecretValue
```
操作
Delegate必须具备访问外部密钥管理器的网络权限

SSH Key Connection Failures

SSH密钥连接失败

Verify the private key is in PEM format
Check that the target server accepts key-based authentication
If using KeyPath, confirm the key file exists on the delegate host
Test with
```
credentialType: Password
```
first to isolate key-specific issues

验证私钥是否为PEM格式
检查目标服务器是否接受基于密钥的认证
如果使用KeyPath，确认密钥文件存在于Delegate主机上
先使用
```
credentialType: Password
```
进行测试，以排查密钥相关问题

Security Best Practices

安全最佳实践

Use external secret managers (Vault, AWS SM) for production secrets
Scope secrets as narrowly as possible -- prefer project over account
Never output secret values in pipeline logs
Rotate secrets regularly and update references
Audit secret access via the
```
/audit-report
```
skill

生产环境密钥使用外部密钥管理器（Vault、AWS SM等）
尽可能缩小密钥的范围——优先使用项目级而非账号级
切勿在流水线日志中输出密钥值
定期轮换密钥并更新引用
通过
```
/audit-report
```
Skill审计密钥访问情况