Create Secret Skill

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

MCP v2 Tools Used

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

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

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

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

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}$

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

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)

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