Create a connector using YAML

This topic explains how to add a connector using the YAML Builder.

Harness connectors integrate Harness with your cloud platforms, codebase and artifact repositories, and collaboration and monitoring tools. You can add a connector using the Harness UI or using YAML in the Harness YAML Builder.

This topic shows you how to add a connector using the YAML Builder.

---

What you will learn from this topic

• How to create a secret to store the credentials your connector uses

• How to create a connector using the YAML Builder

• How to check the connection test status after you save a connector

• How to skip connector preflight checks in restricted network environments

---

Before you begin

• Harness account and project: You need access to a Harness account and project.

• Target system credentials: You need the credentials, such as a username and password or an SSH key, that your connector uses to authenticate with the target system.

---

Create a secret

Connectors typically use passwords or SSH keys to authenticate with platforms and tools. In Harness, you create a Harness secret for the password or SSH key, and then reference that secret's identifier when you create your connector.

Perform the following steps to create a secret:

1. In your Project Settings, Organization Settings, or Account Settings, click Secrets.

2. Click Create via YAML Builder.

3. Use a snippet to create the secret. You can create a secret at the project, organization, or account scope.

4. Click Save Changes.

Here is an example of a Harness inline text secret in YAML:

Sample secret YAML

secret:
  type: SecretText
  name: docs-dockerhub-password
  identifier: docsdockerhubpassword
  orgIdentifier: Doc
  tags: {}
  spec:
    secretManagerIdentifier: harnessSecretManager
    valueType: Inline

The identifier value (in this example, docsdockerhubpassword) is what you reference when you add your connector in YAML.

For steps on other types of secrets, go to Secrets.

---

Create the connector

Perform the following steps to create a connector:

1. In your Project Settings, Organization Settings, or Account Settings, click Connectors.

2. Click Create via YAML Builder.

3. Copy and paste the snippet for the connector you want to create.

For example, here is the snippet for a Docker Hub connector:

Sample Docker Hub connector YAML

connector:
  name: SampleDockerConnector
  identifier: SampleDockerConnectorId
  description: Sample Docker Connector
  orgIdentifier: Doc
  projectIdentifier: Example
  type: DockerRegistry
  spec:
    dockerRegistryUrl: somedockerregistryurl # Replace with your Docker registry URL
    providerType: DockerHub
    auth:
      type: UsernamePassword
      spec:
        username: someuser # Replace with your Docker registry username
        passwordRef: somepasswordref # Replace with the identifier of your Harness secret

Perform the following steps to configure the snippet for your connector:

1. Replace the values for the name and identifier keys.

2. Replace any URL values with the address of your target system.

3. Provide values for the credentials keys.

4. For any password or key field, paste the secret's identifier value.

For example, using the identifier from the secret created earlier (docsdockerhubpassword), the Docker Hub connector configuration becomes:

Example Docker Hub connector YAML

connector:
  name: ExampleDockerConnector
  identifier: ExampleDockerConnectorId
  description: Example Docker Connector
  orgIdentifier: Doc
  projectIdentifier: Example
  type: DockerRegistry
  spec:
    dockerRegistryUrl: https://registry.hub.docker.com/v2/
    providerType: DockerHub
    auth:
      type: UsernamePassword
      spec:
        username: [e-mail]
        passwordRef: docsdockerhubpassword

1. Click Save Changes.

---

Test connection

After you click Save Changes, Harness runs a connection test using the credentials and connectivity mode in your YAML configuration and shows the result under Connectivity Status, such as Success, along with the timestamp of the last status check.

To rerun the test after you save the connector, click Connection Test.

If the test fails, review the error details, correct the credentials or connectivity settings in your connector YAML, and click Connection Test again.

---

Skip connector preflight checks

By default, Harness performs a connection test (preflight check) when you create or update a connector to validate that the credentials are correct and the remote service is accessible. In some environments with network restrictions, split DNS, proxy configurations, or restrictive firewall policies, these connection tests can fail even though the connector works properly at runtime.

If you need to skip connector preflight checks, add the ignoreTestConnection: true property to your connector's YAML configuration. This requires the CI_IGNORE_TEST_CONNECTION feature flag to be enabled for your account. Contact Harness Support to enable this feature flag.

When both the feature flag and the ignoreTestConnection property are enabled, connection tests always return as successful without performing actual connectivity validation.

Here is an example with ignoreTestConnection enabled:

Example connector YAML with ignoreTestConnection enabled

connector:
  name: ExampleDockerConnector
  identifier: ExampleDockerConnectorId
  description: Example Docker Connector
  orgIdentifier: Doc
  projectIdentifier: Example
  type: DockerRegistry
  spec:
    dockerRegistryUrl: https://registry.hub.docker.com/v2/
    providerType: DockerHub
    auth:
      type: UsernamePassword
      spec:
        username: [e-mail]
        passwordRef: docsdockerhubpassword
    ignoreTestConnection: true

Use this property carefully. Skipping connection tests means Harness does not validate whether the connector credentials are correct or the remote service is accessible. Only use this when you are certain the connector works at runtime despite failing preflight checks.

---

Next steps

• Connectors overview: Understand connector categories, scope, and connectivity mode.

• Secrets: Store and manage the credentials your connectors reference.

• Manage access control for connectors: Control who can view, create, edit, and use connectors.