Create Secret Skill

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

MCP v2 Tools Used

Secret Types

SecretText

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

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.

Secret Scopes

Instructions

Step 1: Determine Requirements

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

Step 2: Check for Existing Secrets

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

Step 3: Create the Secret

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

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

Referencing Secrets in Pipelines

# 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:

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

In service variables:

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

Naming Conventions

Identifier must match: ^[a-zA-Z_][0-9a-zA-Z_]{0,127}$

Examples

Create a GitHub PAT secret

/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

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

Create a Vault-referenced secret

/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 WinRM credentials

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

Error Handling

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.

Troubleshooting

Secret Not Accessible in Pipeline

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

External Secret Manager Errors

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

SSH Key Connection Failures

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

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