> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/triggers/trigger-on-a-new-artifact.md).

# Trigger pipelines on a new artifact

Trigger Harness pipelines in response to a new artifact version being added to a registry.

You can trigger Harness pipelines in response to a new artifact version being added to a registry. For example, every time a new Docker image is pushed to your Docker Hub repository, it triggers a pipeline that deploys it automatically.

***

### What you will learn in this topic <a href="#what-you-will-learn-in-this-topic" id="what-you-will-learn-in-this-topic"></a>

By the end of this topic, you will be able to:

* Identify the [supported artifact providers](#supported-artifact-providers) for artifact triggers.
* [Create an artifact trigger](#create-an-artifact-trigger) and configure the connector, conditions, and inputs.
* [Set the artifact tag](#set-the-artifact-tag-to-deploy) to control which version the pipeline deploys.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before you create an artifact trigger, ensure you have the following:

* **A Harness pipeline**: An existing pipeline to attach the trigger to.
* **Pipeline access**: [Permissions](/harness-platform/3.0/harness-platform-resources/platform-access-control/add-manage-roles.md#manage-roles-in-harness) to create and edit triggers on the pipeline.
* **A connector**: A connector to the artifact registry you want to poll. The connector type must match the artifact provider you select.

***

### How artifact triggers work <a href="#how-artifact-triggers-work" id="how-artifact-triggers-work"></a>

Artifact triggers listen to the registry where one or more of the artifacts in your pipeline are hosted. Harness polls the registry continuously using a perpetual task framework. When a new artifact version is detected and any conditions you set are met, the trigger fires and runs the pipeline.

You can set conditions on the trigger, such as matching a Docker tag or a build number pattern. When the trigger fires, Harness resolves `${{trigger.artifact.build}}` in the pipeline to the version that fired the trigger.

{% hint style="info" %}
If more than one artifact is collected during the polling interval (one minute), only one deployment starts by default, using the last artifact collected. To trigger a separate deployment for each artifact collected, navigate to **Default Settings → Pipeline** and enable **Execute Triggers With All Collected Artifacts or Manifests**.
{% endhint %}

***

### Supported artifact providers <a href="#supported-artifact-providers" id="supported-artifact-providers"></a>

You can create artifact triggers for the following registries:

* Docker Registry
* ECR (Amazon Elastic Container Registry)
* ACR (Azure Container Registry)
* Google Artifact Registry (GAR)
* GitHub Package Registry (GPR)
* Nexus3
* Amazon S3

***

### Artifact trigger behavior <a href="#artifact-trigger-behavior" id="artifact-trigger-behavior"></a>

Review the following before you create an artifact trigger:

* **Trigger based on file name**: The trigger fires based on *file names*, not metadata changes.
* **Do not trigger on the latest tag**: Do not use the **latest** tag as a trigger condition. Harness only has the tag name as metadata, and because the name never changes, Harness cannot detect a new push. The trigger will not fire.
* **Control access with repository RBAC**: Use your repository's RBAC to control who can push artifacts that start the trigger. Harness RBAC controls who can create and manage the trigger itself.
* **Allow time for polling to start**: After you create or update a trigger, wait five to ten minutes for the polling job to start before pushing an artifact. During this window, the trigger is not yet in a working state.
* **Polling and disabled triggers**: Polling stops when you disable a trigger. After you re-enable it, Harness treats it as a new polling job. Harness recommends pushing an artifact to verify the flow after re-enabling.
* **Use lexically sortable tags**: Image tags are listed in lexical order due to a Docker API limitation. To ensure the image pushed last is used when multiple images are pushed within a short period, use build numbers or tags that sort lexically by creation date.
* **Verify a new trigger**: After creating a trigger for the first time, push an artifact to confirm it fires as expected.

{% hint style="info" %}
When you link a Docker repository to a new trigger, the status remains `pending` until there are available tags. After the first push, the status changes to `success`.
{% endhint %}

***

### Set the artifact tag to deploy <a href="#set-the-artifact-tag-to-deploy" id="set-the-artifact-tag-to-deploy"></a>

In your pipeline's service definition, set the artifact **tag** field to control which version the pipeline deploys when the trigger fires. You can use the following values:

* **`${{trigger.artifact.build}}`**: Deploy the artifact version that fired the trigger.
* **A fixed tag value**: Always deploy a specific version, regardless of what fired the trigger.

In the pipeline YAML, reference the trigger expression as follows:

```yaml
service:
  items:
    - id: your_service_id
      with:
        overlay:
          serviceDefinition:
            spec:
              artifacts:
                primary:
                  sources:
                    - spec:
                        tag: ${{trigger.artifact.build}}
                      identifier: my_artifact
                      type: DockerRegistry
              type: Kubernetes
```

***

### Create an artifact trigger <a href="#create-an-artifact-trigger" id="create-an-artifact-trigger"></a>

To create an artifact trigger, do the following:

1. Open your Harness pipeline.
2. Select the **Triggers** tab.
3. Click **+ Create trigger**. The **New Trigger** panel opens.
4. Under **Artifact**, select the registry type for your artifact (for example, **Docker**, **ECR**, or **GAR**). The **Create \[Provider] trigger** panel opens.
5. In **Name**, enter a name for the trigger. Harness generates an **Id** from the name automatically.
6. In **Connector**, select or create a connector to the artifact registry. The connector type must match the artifact registry you selected. See [connector setup](#connector-setup-by-registry) below for registry-specific requirements.
7. (Optional) In **Conditions**, click **+ Add** to set filter conditions. The trigger only fires when all conditions match. See [Configure conditions](#configure-conditions) below.
8. (Optional) In **Inputs**, click **+ Add** to provide runtime input values the pipeline needs when the trigger runs it.
9. Click **Create**.

***

### Connector setup by registry <a href="#connector-setup-by-registry" id="connector-setup-by-registry"></a>

{% tabs %}
{% tab title="Docker Registry" %}
Use a **Docker Registry** connector.

* To connect to Docker Hub (public), set the registry URL to `https://registry.hub.docker.com/v2/`.
* To connect to a private Docker registry, set the registry URL to `https://index.docker.io/v2/`.

Go to the [Docker Registry connector settings reference](/harness-platform/3.0/harness-platform-resources/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference.md) to configure the connector.
{% endtab %}

{% tab title="ECR" %}
Use an **AWS** connector with access to the ECR registry.

After selecting the connector, complete the following fields:

| Field          | Required | Description                                                                                              |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| **Region**     | Yes      | The AWS region where the ECR registry is hosted.                                                         |
| **Image path** | No       | The repository image path to poll. Selected from a dropdown populated by the connector.                  |
| **Registry**   | No       | The ECR registry ID (AWS account ID). Leave blank to use the default registry for the connected account. |

Go to the [AWS connector settings reference](/harness-platform/3.0/harness-platform-resources/connectors/cloud-providers/ref-cloud-providers/aws-connector-settings-reference.md) to configure the connector.
{% endtab %}

{% tab title="ACR" %}
Use a **Microsoft Azure** connector.

The connector must have access to the subscription, registry, and repository you want to poll.

Go to [Add a Microsoft Azure Cloud connector](/harness-platform/3.0/harness-platform-resources/connectors/cloud-providers/add-a-microsoft-azure-connector.md) to configure the connector.
{% endtab %}

{% tab title="Google Artifact Registry (GAR)" %}
Use a **GCP** connector with access to the Google Artifact Registry project.

After selecting the connector, complete the following fields:

| Field               | Required | Description                                                                                 |
| ------------------- | -------- | ------------------------------------------------------------------------------------------- |
| **Project ID**      | Yes      | The GCP project ID that contains the artifact registry.                                     |
| **Region**          | Yes      | The region where the repository is hosted. Selected from a dropdown.                        |
| **Repository name** | Yes      | The GAR repository to poll. Selected from a dropdown populated by the connector and region. |
| **Package**         | Yes      | The specific package within the repository to monitor. Selected from a dropdown.            |

Go to [Add a Google Cloud Platform (GCP) connector](/harness-platform/3.0/harness-platform-resources/connectors/cloud-providers/connect-to-google-cloud-platform-gcp.md) to configure the connector.
{% endtab %}

{% tab title="GitHub Package Registry (GPR)" %}
Use a **GitHub** connector with access to the GitHub organization or account that owns the packages.

The connector must have permission to read packages from the GitHub Package Registry.
{% endtab %}

{% tab title="Nexus3" %}
Use a **Nexus** connector pointing to your Nexus Repository Manager 3 instance.

The connector must have access to the repository you want to poll.
{% endtab %}

{% tab title="Amazon S3" %}
Use an **AWS** connector with access to the S3 bucket.

When configuring the trigger, you specify a **Bucket Name** and a **File Path Regex** (for example, `todolist*.zip`) to match the artifacts to monitor. Use `*` for wildcard matching (not `.*`).

Go to the [AWS connector settings reference](/harness-platform/3.0/harness-platform-resources/connectors/cloud-providers/ref-cloud-providers/aws-connector-settings-reference.md) to configure the connector.
{% endtab %}
{% endtabs %}

***

### Configure conditions <a href="#configure-conditions" id="configure-conditions"></a>

In **Conditions**, specify the conditions that must be met for the trigger to run the pipeline. The pipeline runs only when all conditions match. Conditions are optional.

An artifact trigger supports the following condition types:

* **Event Condition**: Match against the incoming **Artifact Build** value (the tag, version, or file name). Select an operator and enter a value or pattern.
* **Metadata Conditions**: Match against artifact metadata attributes such as image, tag, or SHA.
* **JEXL Condition**: Enter a JEXL expression for advanced logic that combines multiple attributes or values.

**Regex and wildcards**

You can use wildcards in condition values and enable **Regex** to match using Java regex patterns.

* With regex enabled and the build value `todolist-v2.0`, the pattern `todolist-v\d.\d` matches.
* To match all files ending in `-DEV.tar`, use `.*-DEV\.tar`.
* To match any value, use `.*` (not `*`).

If a regex expression does not result in a match, Harness ignores the trigger for that artifact version.

***

### Define a multi-region artifact source <a href="#define-a-multi-region-artifact-source" id="define-a-multi-region-artifact-source"></a>

Configure a multi-region artifact source when the same artifact version is replicated across multiple regions and you want the pipeline to trigger only when the version is available in all of them. This is supported for registries where each region is configured as a separate artifact source — for example, Google Artifact Registry (GAR).

Each artifact source you add represents one region. Harness evaluates conditions across all configured regions and fires the pipeline only when the version is present in every region.

To configure a multi-region artifact source, do the following:

1. In your pipeline, select the **Triggers** tab.
2. Create an artifact trigger and configure the primary artifact source (the first region). Fill in all required fields — for GAR, this includes **Connector**, **Project ID**, **Region**, **Repository name**, and **Package**.
3. After saving the primary source, select **Define Multi Region Artifact Source**.
4. For each additional region, add an artifact source with the same connector (or a region-specific connector), and set the appropriate **Region**, **Repository name**, and **Package** values.
5. (Optional) Add conditions that apply across all regions.
6. Click **Create**.

***

### Enable or disable a trigger <a href="#enable-or-disable-a-trigger" id="enable-or-disable-a-trigger"></a>

Use the enabled toggle on the **Triggers** list page to enable or disable a trigger. When disabled, polling stops. When re-enabled, Harness starts a new polling job.

***

### Reuse trigger YAML to create new triggers <a href="#reuse-trigger-yaml-to-create-new-triggers" id="reuse-trigger-yaml-to-create-new-triggers"></a>

You can copy a trigger's YAML and paste it when creating a new trigger. This is useful when you have conditions or input configurations you do not want to re-enter manually.

{% hint style="info" %}
Trigger artifact expressions such as `${{trigger.artifact.build}}` used in a pipeline are resolved when you rerun a pipeline that was activated by a trigger.
{% endhint %}

***

### Related articles <a href="#related-articles" id="related-articles"></a>

* [Schedule pipelines using triggers](/harness-platform/3.0/harness-platform-resources/triggers/schedule-pipelines-using-cron-triggers.md): Run pipelines on a Cron schedule.
* [Trigger pipelines using Git events](/harness-platform/3.0/harness-platform-resources/triggers/triggering-pipelines.md): Run pipelines in response to Git push, PR, or tag events.
* [Customize trigger input configuration using override YAML](/harness-platform/3.0/harness-platform-resources/triggers/customize_trigger_input_configuration_using_override_yaml.md): Override specific input set values in the trigger configuration.

{% @harness-feedback/feedback %}