> 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/release-orchestration/use-release-orchestration/release-orchestration-artifacts/artifact-tracker-getting-started.md).
# Get Started with Artifact Tracker and Changesets
Learn how to set up Artifact Tracker to automatically track container images and compute changesets between versions.
{% hint style="success" %}
This feature is in Limited GA and requires enablement. [View all early access features.](/release-notes/features.md)
{% @harness-feature-flag-access/request-feature-flag-access module="release-orchestration" pagePath="release-orchestration/use-release-orchestration/release-orchestration-artifacts/artifact-tracker-getting-started" featureFlags="%5B%7B%22name%22%3A%22Changeset%20Configuration%22%2C%22key%22%3A%22RMG\_ENABLE\_CHANGESET\_CONFIGURATION%22%2C%22status%22%3A%22LIMITED\_GA%22%2C%22description%22%3A%22Enables%20changeset%20configuration%20and%20computation%20between%20artifact%20versions.%22%7D%2C%7B%22name%22%3A%22Changeset%20Pipeline%20Execution%22%2C%22key%22%3A%22PIPE\_DIRECT\_PIPELINES\_EXECUTION%22%2C%22status%22%3A%22LIMITED\_GA%22%2C%22description%22%3A%22Enables%20the%20pipeline%20execution%20required%20to%20compute%20changesets.%22%7D%2C%7B%22name%22%3A%22Dynamic%20Queue%20Activity%20Targets%22%2C%22key%22%3A%22RMG\_ENABLE\_WEBHOOK\_QUEUE\_SUPPORT%22%2C%22status%22%3A%22LIMITED\_GA%22%2C%22description%22%3A%22Enables%20the%20RO%20Notify%20step%20to%20appear%20in%20the%20step%20library.%22%7D%5D" %}
{% endhint %}
Artifact Tracker catalogs every container image your pipelines produce and computes a changeset for each artifact version relative to the previous one. A changeset includes the commits and, optionally, Jira tickets introduced between versions. When you need to know what changed in a release, the changeset shows the changes without requiring you to search Git history.
This topic covers the one-time setup and explains how to use the day-to-day views after you configure Artifact Tracker.
{% hint style="info" %}
**FEATURE AVAILABILITY**
Artifact Tracker and Changesets require the following feature flags to be enabled. Contact [Harness Support](mailto:support@harness.io) to enable these flags for your account:
* `RMG_ENABLE_CHANGESET_CONFIGURATION`: Enables changeset configuration and computation between artifact versions.
* `PIPE_DIRECT_PIPELINES_EXECUTION`: Enables the pipeline execution required to compute changesets.
* `RMG_ENABLE_WEBHOOK_QUEUE_SUPPORT`: Enables the **Publish Events** step to appear in the step library.
{% endhint %}
***
### Before you begin
You need the following connectors configured. You can reuse existing connectors or create new ones.
* **Git connector**: GitHub, GitLab, Bitbucket, Git, or Harness Code connector to clone the repository and diff commits between versions. Go to [Create a Git connector](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-connector-settings-reference) to create one. If your build pipeline has a codebase configured, Release Management can use that pipeline's git connector or Harness Code repository instead, so this connector is optional for artifacts built by that pipeline.
* **Jira or ServiceNow connector**: Links tickets to commits. Go to [Connect to Jira](https://developer.harness.io/harness-platform/use-harness-platform/connectors/ticketing-systems/connect-to-jira) or [ServiceNow connector settings reference](https://developer.harness.io/harness-platform/use-harness-platform/connectors/ticketing-systems/connect-to-service-now) to create one.
* **Kubernetes cluster connector**: Runs the pod that performs git diff and ticket lookup. Go to the [Kubernetes cluster connector settings reference](https://developer.harness.io/harness-platform/use-harness-platform/connectors/cloud-providers/ref-cloud-providers/kubernetes-cluster-connector-settings-reference) to create one.
* **Docker registry connector**: Pulls the `alpine` and `alpine/git` images for git diff and ticket lookup. Go to [Docker connector settings reference](https://developer.harness.io/harness-platform/use-harness-platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) to create one.
* **Project access**: View or Execute permissions on pipelines to view artifact details and changesets. Go to [RBAC in Harness](https://developer.harness.io/harness-platform/use-harness-platform/platform-access-control) to configure roles.
***
### How Artifact Tracker works
The following diagram shows how Artifact Tracker captures and processes container images:
```mermaid
flowchart TD
A[Build pipeline
publishes image] --> B[Publish Events step
reports artifact]
B --> C[Release Management
ingests version]
C --> D[Match to
mapped service]
D --> E{Release
listening?}
E -->|Yes| F[Link to release]
E -->|No| G[Store in
catalog only]
F --> H[Git diff vs
previous version]
G --> H
H --> I[Extract commits]
I --> J{Ticket
connector?}
J -->|Yes| K[Scan messages
for ticket IDs]
J -->|No| L[Changeset:
commits only]
K --> M[Resolve tickets
from Jira/ServiceNow]
M --> N[Changeset:
commits + tickets]
L --> O[View in Explorer
and Changesets tab]
N --> O
```
Artifact Tracker records every artifact regardless of whether a release is running. Changesets require a Git connector to compute the commit diff, either configured on the service mapping or detected automatically from the build pipeline that produced the artifact. Linking tickets to changesets requires a ticket connector and a regex pattern to extract ticket IDs from commit messages.
***
### Add the Publish Events step to your build pipeline
The Publish Events step is a pipeline step that reports details of published artifacts to Release Management. This step acts as the bridge between your CI/CD pipelines and Release Orchestration, enabling automatic tracking of every artifact your pipelines produce.
When you use native Harness build and push steps (such as Build and Push to Docker Registry), artifacts produced within the pipeline are **captured automatically** without additional configuration. The step detects these artifacts and forwards their metadata to the Artifact Tracker catalog.
It runs immediately after your artifact is published and completes in seconds. It does not modify or interact with the artifact itself. It only reports metadata to Release Management for tracking and changeset computation.
{% hint style="info" %}
The Publish Events step is not supported inside a CI stage. If your artifact is published from a CI stage, add a separate Custom stage after it and place the step there.
{% endhint %}
{% hint style="warning" %}
The Publish Events step does not appear in the step library unless the `RMG_ENABLE_WEBHOOK_QUEUE_SUPPORT` feature flag is enabled for your account. If you cannot find it, contact [Harness Support](mailto:support@harness.io) to have this flag enabled.
{% endhint %}
Perform the following steps to add the Publish Events step to your build pipeline:
1. In your build pipeline, click **Add Stage** after the stage that publishes the artifact.
2. Select **Custom** as the stage type, then click **Set Up Stage**.
3. Enter a stage name, such as `Notify Release Management`, then click **Save**.
4. In the **Execution** tab, click **Add Step**.
5. Select **Publish Events** from the **Release Orchestration** category in the step library.
6. Configure the step:
* **Name**: Enter a step name, such as `Report Artifact`.
* **Timeout**: Keep the default or enter a value of at least `10s`.
* Leave **Event Payload** empty if you are using native Harness build and push steps. The step automatically detects the published artifacts and the Git details of the build.
7. Click **Apply Changes**, then **Save** the pipeline.
{% hint style="info" %}
**ADVANCED CONFIGURATION**
By default, the Publish Events step detects the artifacts published by the native Harness build and push steps, along with the Git details of the build. Release Management reads each artifact's registry, path, and tag from the image reference.
To report artifacts published by other steps (for example, a **Run** step that calls `docker push`), or to override the Git details the step detects, add key-value pairs under **Event Payload**. Values accept fixed values and expressions. To change how an artifact is matched to a service, update its [service mapping](#map-your-services).
| Key | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `artifacts_json` | Images to report, as a JSON string. Use it only when the step detects no artifacts. Each image requires `imageName` and `tag`. For example, `{"images":[{"imageName":"gcr.io/acme/api","tag":"<+pipeline.sequenceId>"}]}`. |
| `commit_sha` | Full Git commit SHA the artifact was built from, for example `<+codebase.commitSha>`. |
| `repo_name` | Repository name, for example `<+codebase.repoUrl>`. |
| `branch` | Git branch the artifact was built from, for example `<+codebase.branch>`. |
| `git_connector_ref` | Git connector used to compute the changeset. |
| `git_provider_type` | Git provider type, either `THIRD_PARTY` or `HARNESS_CODE`. |
Keep the following in mind:
* A key you set takes precedence over the value the step detects. A key with an empty value is treated as not set.
* To override the Git source, set `git_provider_type` to `HARNESS_CODE` for a Harness Code repository (no connector is needed), or set `git_connector_ref` for a third-party Git provider (`git_provider_type` defaults to `THIRD_PARTY`).
* The step detects Git details only when it detects artifacts. When you use `artifacts_json`, set `commit_sha`, `repo_name`, and `branch` yourself. Without `commit_sha`, Release Management records the artifact but cannot compute a changeset for it.
* Git details apply to every image in `artifacts_json`. To report images built from different commits, use one Publish Events step per commit.
* In `imageName`, include the registry host, such as `docker.io/acme/api` or `gcr.io/acme/api`, or provide the optional `url` field. Without a host, the registry is left empty and the artifact is tracked separately from artifacts that the step detects, which carry their registry. The registry and path must match a service mapping for the artifact to be linked to a service.
* Release Management does not validate `artifacts_json` when the step runs. If it is malformed or an image is missing `imageName` or `tag`, the step still succeeds but the artifact does not appear in the catalog. Verify the first run in **Artifacts** > **Explorer**.
For artifacts built outside Harness, or for the full list of accepted keys, go to the [webhook signal API](/release-orchestration/use-release-orchestration/release-orchestration-artifacts/webhook-signal-api.md#request-body).
{% endhint %}
***
### Configure default connectors
Default connectors apply to all mapped services unless overridden at the service mapping level. Connector configuration is available at the project, organization, or account level. The defaults you set in this topic are inherited by every mapped service unless overridden.
Perform the following steps to configure default connectors:
1. In Harness, navigate to **Release Orchestration**.
2. In the left navigation, under **Artifacts**, click **Configurations**.
3. Click **Connectors**.
4. Configure the following integrations:
**Git integration**
Configure the Git connector to enable commit comparisons between artifact versions.
Perform the following steps to configure Git integration:
1. Under **Git Integration**, click **Git Provider**.
2. Select the **Harness Code Repository** or a third-party Git provider.
3. If you selected a third-party provider, select the **Git Connector** from the dropdown.
4. Click **Save**.
{% hint style="info" %}
**Automatic git connector detection**
If your build pipeline has a configured codebase, the Publish Events step automatically reports the pipeline's git connector or Harness Code repository to Release Management, which then uses it to compute the changeset. This detected connector takes precedence over the default or service-mapping-level Git connector, so a service mapping with no Git connector configured can still produce a changeset for an artifact built by such a pipeline. If the build pipeline has no codebase configured, Release Management falls back to the default or service-mapping-level Git connector you configure in this topic.
{% endhint %}
**Ticket integration**
Configure the ticket connector to link Jira or ServiceNow tickets to changesets.
Perform the following steps to configure ticket integration:
1. Under **Ticket Integration**, click **Ticket Connector**.
2. Select your Jira or ServiceNow connector from the dropdown.
3. (Optional) Enter a **Ticket Regex Pattern** if you need a different pattern from the default `[A-Z]+-[0-9]+`. The default pattern matches Jira-style ticket keys, such as `RM-123` `ABC-4567` (one or more uppercase letters, a dash, then one or more digits). Leave blank to use the default.
4. Click **Save**.
**Infrastructure**
Configure the Kubernetes cluster connector and namespace where changeset pods run.
Perform the following steps to configure the infrastructure:
1. Under **Infrastructure**, select the **Kubernetes Cluster Connector** from the dropdown.
2. Enter the **Namespace** where the changeset pods will run.
3. Click **Save**.
**Artifact registry**
Configure the Docker registry connector to pull container images for git diff and ticket lookup.
Perform the following steps to configure the artifact registry:
1. Under **Artifact Registry**, select the **Docker Registry Connector** from the dropdown.
2. Click **Save**.
**Semantic versioning**
Semantic versioning is enabled by default. When enabled, changesets compare semantic versions instead of arrival order.
For example, if `payment-service` has versions `1.0.0` and `2.0.0`, and hotfix `1.0.1` arrives later, the changeset compares `1.0.0` to `1.0.1` instead of `2.0.0` to `1.0.1`.
Perform the following steps to disable semantic versioning:
1. Under **Semantic Versioning**, toggle the setting to **Off**.
2. Click **Save**.
***
### Map your services
Service mappings connect artifact paths to Harness CD services and apply default connector settings. Artifacts that do not match any mapping are still stored in the catalog, but changesets are not computed until you create a mapping.
Perform the following steps to create a service mapping:
1. In the left navigation, under **Artifacts**, click **Configurations**.
2. Click **Service Mappings**.
3. Click **Create Service Mapping**.
4. Configure the mapping:
* **Artifact Path**: Enter the artifact path, for example `my-org/payment-service`.
* **Artifact Registry**: (Optional) Select a specific registry to scope the mapping.
* **Service Ref**: Select the Harness CD service this artifact belongs to.
* **Service scope**: You can select a service from any scope, account, organization, or project, regardless of the scope at which you create the mapping.
5. (Optional) Override any default connector settings for this specific mapping:
* **Git Connector**: Select a different Git connector if this service uses a different repository.
* **Ticket Connector**: Select a different ticket connector or modify the ticket regex pattern.
* **Semantic Versioning**: Toggle to enable or disable for this specific service.
6. Click **Save**.
Repeat these steps for each service you want to track.
***
### Link artifacts to releases (optional)
Artifacts are captured in the catalog regardless of this step. Complete this step only if you want to link specific artifact versions to a release.
Perform the following steps to link artifacts to a release:
1. Open the release process where you want to capture artifacts.
2. Add a **Pipeline Queue** activity to the release process.
3. Configure the Pipeline Queue activity to listen for the build pipeline that publishes the artifact.
While the Pipeline Queue activity is running, any matching pipeline execution that includes the Publish Events step automatically links its published artifacts to the release.
If a build pipeline directly triggers the release, instead of being monitored by a Pipeline Queue activity, its published artifacts are automatically linked to that release without additional configuration.
If no release is listening, artifacts are still captured in the catalog but are not attached to a specific release.
***
### How artifacts are automatically tracked
After you complete the setup steps, the process runs automatically. When your build pipeline publishes a new image version:
1. The Publish Events step reports the artifact details to Release Management, which records the artifact in the catalog.
2. If a release is listening (from the Link artifacts to releases step) and a service mapping exists (from the Map your services step), the artifact is linked to the release.
3. If a Git connector is configured, Release Management compares this version to the previous one and lists the commits.
4. If a ticket connector and regex pattern are configured, commit messages are scanned for ticket IDs, which are resolved against Jira or ServiceNow and attached to the changeset.
The first artifact received for a mapping has no previous version to diff against. It becomes the baseline. The next version produces the first changeset.
***
### View artifact catalog and changesets
After setup and pipeline runs complete, view artifacts and changesets.
**View all artifacts**
Perform the following steps to view all artifacts:
1. In the left navigation, under **Artifacts**, click **Explorer**.
2. Use the grouping options to filter by service or artifact path.
3. Click any artifact to view all tags and versions for that artifact.
**View changesets**
Perform the following steps to view changesets:
1. In the left navigation, under **Artifacts**, click **Changesets**.
2. Use the filters to search by:
* Artifact path
* Commit SHA
* Ticket ID
3. Click any changeset to view:
* Commits introduced between the two versions
* Linked Jira or ServiceNow tickets
* Changeset status (Success, Failed, or Running)
**View changesets in a release**
Perform the following steps to view changesets in a release:
1. Navigate to the specific release.
2. Click the **Changesets** tab.
3. View all changesets tied to this release, including:
* Commit lists
* Linked tickets
* Changeset status
***
### Manage changesets
Retry failed changesets and edit tags when the baseline version is incorrect.
**Retry a failed changeset**
If a changeset fails because of a git clone timeout or Jira being unreachable, perform the following steps to retry:
1. Navigate to **Artifacts** > **Changesets**.
2. Click the failed changeset.
3. Review the error logs to understand the failure.
4. Click **Retry Changeset** to recompute the changeset.
**Edit changeset tags**
If the baseline version is incorrect because an out-of-band hotfix was not captured, perform the following steps to edit tags:
1. Navigate to **Artifacts** > **Changesets**.
2. Click the changeset you want to edit.
3. Click **Edit Tags**.
4. Update the **From Tag** and **To Tag** tags to the correct versions.
5. Click **Apply**, then click **Retry Changeset** to recompute the diff.
{% hint style="info" %}
Editing tags only affects the selected changeset. It does not change how future artifacts resolve their baseline.
{% endhint %}
***
### Connector configuration and available data
The following table shows what data is available based on the connectors you configure:
***
### Troubleshooting
No changeset appears for a new artifact version, even though the Publish Events step ran successfully
Confirm that a service mapping exists for the artifact path and registry. Navigate to Artifacts > Configurations > Service Mappings and verify the artifact path matches exactly. If a release is required, confirm a Pipeline Queue activity is actively listening for the build pipeline.
Changeset shows commits but no linked tickets.
Verify that a ticket connector is configured in Artifacts > Configurations > Connectors > Ticket Integration. Confirm the ticket regex pattern matches the format used in your commit messages. Check that commit messages actually contain ticket IDs. The default regex pattern is \[A-Z]+-\[0-9]+, which matches Jira-style keys like RM-123.
Changeset failed with a git clone timeout or connection error
Open the changeset and review the error logs. Verify the Git connector has the correct credentials and network access. Check that the Kubernetes cluster connector has permissions to create pods in the specified namespace. Retry the changeset after fixing the connector permissions or network issues.
Artifact is tracked but not linked to any release
Confirm a Pipeline Queue activity is configured in the release process and is actively listening when the Publish Events step runs. Artifacts are still captured in the catalog and can be linked to a release later.
The Publish Events step fails in a CI stage
The Publish Events step is not supported inside a CI stage. Add a separate Custom stage after the CI stage and place the Publish Events step in the Custom stage instead.
***
### Next steps
After configuration, you can:
* Go to [Modeling Releases](/release-orchestration/use-release-orchestration/release-orchestration-releases/modeling-releases.md) to learn how to link artifacts to releases.
* Go to the [Release Calendar](/release-orchestration/use-release-orchestration/release-orchestration-releases/release-calendar.md) to visualize releases and artifacts on a calendar view.
* Go to [Release Notifications](/release-orchestration/use-release-orchestration/notifications.md) to set up Slack alerts for artifact and changeset events.
{% @harness-feedback/feedback %}