> 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/continuous-delivery/use-gitops/dashboards/gitops-dashboards.md).

# GitOps dashboards

Monitor GitOps applications, sync operations, agents, clusters, and repositories in Harness Dashboards, and use the dashboard controls to explore the data.

Harness Dashboards brings GitOps data into a centralized view, helping you monitor the health and synchronization status of your GitOps applications alongside other software delivery data.

Use dashboards to monitor GitOps applications, including their health and sync status, associated clusters and repositories, GitOps Agents, and sync operations. You can also filter GitOps data by organization or project to focus on the resources relevant to your teams.

For example, you can build widgets that show:

* Which applications are out of sync or unhealthy.
* Whether syncs were triggered by Harness pipelines or directly in Argo CD.
* Which GitOps Agents have an upgrade available.
* Which clusters or repositories have a failing connection status.

GitOps data is streamed to Dashboards as changes occur, helping you monitor the latest reported state of your GitOps resources.

The dashboard in this topic is an example. Dashboards are fully customizable and have no default layout, so you build the widgets that match what your teams need to monitor.

{% hint style="info" %}

* This topic applies to Harness Dashboards with the new experience. GitOps data and the dashboard UI described here are not available in legacy Dashboards.
* GitOps data in Dashboards is rolling out in phases. The availability of standard dashboard templates may vary across accounts. Contact [Harness Support](mailto:support@harness.io) for more details.
  {% endhint %}

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

* Understand [GitOps data processing and visualization](#gitops-data-processing-and-visualization).
* Understand the [GitOps data](#gitops-data-in-dashboards) that you can visualize.
* How to [access a GitOps dashboard](#access-a-gitops-dashboard) and read its widgets.
* How to use the [dashboard controls](#use-the-dashboard-controls), including variables and the time range.
* How to [edit a dashboard](#edit-a-dashboard) to add filters and widgets.
* How to [choose GitOps data for a widget](#choose-data-for-a-widget) with the **GitOps** module.
* How to [query GitOps data with Code View](#query-gitops-data-with-code-view).

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

Before using GitOps data in Dashboards, ensure that you have:

* **GitOps resources**: At least one [GitOps Agent](https://developer.harness.io/continuous-delivery/use-gitops/gitops-entities/agents.md) with applications reporting data to Harness.
* **Dashboards experience**: Access to the new Harness Dashboards experience. GitOps data is not available in legacy Dashboards.
* **Required permissions**:
  * **Dashboards**: `core_dashboards_view` to view dashboards, and `core_dashboards_create` or `core_dashboards_edit` to create or modify widgets.
  * **GitOps resources**: View permissions for the resources you want to access, such as `gitops_application_view`, `gitops_agent_view`, `gitops_cluster_view`, and `gitops_repository_view`.

## GitOps data processing and visualization <a href="#gitops-data-processing-and-visualization" id="gitops-data-processing-and-visualization"></a>

Harness makes GitOps data available in Dashboards through the following steps:

1. **GitOps Agent**: The agent in your Kubernetes cluster collects GitOps resource information and reports applications, clusters, repositories, and sync operations to Harness.
2. **Harness GitOps**: Harness receives and stores the reported data.
3. **Data processing**: Harness detects changes to the stored data and streams them for processing. The changes are mapped to the GitOps entities described in [GitOps data in Dashboards](#gitops-data-in-dashboards) and made available for querying.
4. **Dashboards**: Dashboard widgets query the available GitOps entities and visualize the results.

Only the supported GitOps entities described in [GitOps data in Dashboards](#gitops-data-in-dashboards) are made available for querying.

GitOps data is available for querying, so you can build GitOps widgets by selecting the **GitOps** module in the **Choose data** dialog, or by using **Code View**. Go to [Choose data for a widget](#choose-data-for-a-widget) and [Query GitOps data with Code View](#query-gitops-data-with-code-view).

{% hint style="info" %}
**Data availability and historical backfill**

GitOps data is streamed into Dashboards as changes occur. Existing resources and past sync operations are populated by a scheduled historical backfill for each environment, so historical sync records are retained and queryable.

Sync operations captured before pipeline attribution support (release 1.69.0), and syncs triggered through bulk sync, do not have a `plan_execution_id`. They do not link to a Harness pipeline execution.
{% endhint %}

## GitOps data in Dashboards <a href="#gitops-data-in-dashboards" id="gitops-data-in-dashboards"></a>

Harness Dashboards supports five GitOps entity types. These entities represent the GitOps resources and operations available for querying and visualization.

| Entity                                        | What it covers                                                                                                                                                                                                               |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitOps application** (`gitops:application`) | Each application with its name, cluster, destination namespace, destination server, health status, sync status, linked repositories, and creation date.                                                                      |
| **GitOps sync operation** (`gitops:appsync`)  | GitOps application sync operations, including those triggered by Harness pipelines and those initiated directly in Argo CD. A sync operation is an event, which is different from the current sync status of an application. |
| **GitOps agent** (`gitops:agent`)             | Each agent with its type, operator, version, and high availability and disaster recovery settings.                                                                                                                           |
| **GitOps cluster** (`gitops:cluster`)         | Each cluster registered with your GitOps Agents, with its name, server, type, connection status, and Kubernetes version.                                                                                                     |
| **GitOps repository** (`gitops:repository`)   | Each repository registered with your GitOps Agents, with its URL, type, connection type, and connection status.                                                                                                              |

Every entity is scoped to your account, organization, and project, so you can filter any widget by scope.

The **GitOps** module in the **Choose data** dialog provides curated sources for GitOps applications, sync operations, agents, and clusters. To query GitOps repositories, use [Code View](#query-gitops-data-with-code-view).

{% hint style="info" %}
Dashboard data does not include sensitive credentials, such as agent keys, repository passwords, SSH keys, bearer tokens, or TLS certificates. Only the defined fields are available.
{% endhint %}

### Relationships between entities

GitOps entities are related to each other and to your Harness account, organization, and project. You can use these relationships to combine data from multiple entities in a single widget.

* Every entity links to its account, organization, and project.
* Applications, clusters, and repositories link to the agent that manages them. Applications also link to their cluster.
* A sync operation (`gitops:appsync`) records how the sync was triggered:
  * **Pipeline-triggered**: `is_pipeline_triggered` is `true`, and `plan_execution_id` links to the Harness pipeline execution that triggered the sync.
  * **Automated sync**: `is_auto_sync` is `true` when Argo CD automatically syncs changes that it detects in Git.
  * **Manual or direct sync**: `is_pipeline_triggered` and `is_auto_sync` are both `false` when a user starts a sync in the GitOps UI, the Argo CD UI, or the CLI without a pipeline.

## Access a GitOps dashboard <a href="#access-a-gitops-dashboard" id="access-a-gitops-dashboard"></a>

To access a dashboard, log in to Harness and then select **Dashboards**.

1. On the **All dashboards** page, find your GitOps dashboard. To narrow the list, enter a name in **Search** or select **Add filter**.
2. Select the dashboard name to open it.

If no GitOps dashboard template is available to your account, create your own dashboard and add GitOps widgets. Go to [Add a data widget](#add-a-data-widget).

The **All dashboards** page lists each dashboard with its tags, owner, and creation and update dates. Use the sort dropdown to change the list order. The list is sorted by **Recently Updated** by default. To create a dashboard, select **Create dashboard**.

The dashboard opens with its title and description at the top, followed by its creation and last update dates. The widgets appear below the time range controls.

The following screenshot shows an example GitOps dashboard. Your dashboard might look different depending on the widgets you configure.

![Example GitOps dashboard](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-55ea88761e482981d08fcc146769e537dd10e544%2Fgitops-applications-dashboard.png?alt=media)

## Use the dashboard controls <a href="#use-the-dashboard-controls" id="use-the-dashboard-controls"></a>

Use the controls at the top of the dashboard to change what the widgets show and manage the dashboard.

### Dashboard menu

Select the three-dot menu next to **Edit** to open the dashboard menu. Then choose one of the following options:

* **Refresh**: Reload the data in all widgets.
* **Copy as JSON**: Copy the dashboard definition as JSON.
* **Clone**: Create a copy of the dashboard.
* **Export data**: Download the data shown in the dashboard.

### Dashboard variables

Select the **(x)** button to open the **Dashboard Variables** panel. The panel lists the variables that the dashboard passes to widget queries. Use variables to keep widgets in sync with the dashboard time range, or to reuse a value across several widget queries.

The **Time Range** section shows the current selection, for example, **Last 1 Month**, and the variables that the time range sets:

| Name           | Variable        | Value                                 |
| -------------- | --------------- | ------------------------------------- |
| **Start Time** | `${start_time}` | The start of the selected time range. |
| **End Time**   | `${end_time}`   | The end of the selected time range.   |

Below the time range, the panel lists the dashboard filters. When the dashboard has no filters, the panel shows **No field filters configured**. Go to [Edit a dashboard](#edit-a-dashboard) to add a filter.

### Time range

The time range button shows the selected range, its start and end, and the time zone, for example, **Last 1 month (Oct 3, 2026, 09:48 - Nov 3, 2026, 09:48) UTC+00:00**. All widgets use this range.

Perform the following steps to change the time range:

1. Select the time range button.
2. Select how you want to define the range:
   * **Relative**: Select **Last** or **Next**, enter a number, and select a unit, such as **Months**. The two calendars highlight the resulting range.
   * **Calendar periods**: Select a calendar period.
   * **Fixed**: Enter a fixed start and end.
3. In the time zone dropdown, select **Browser Time** to use your browser's time zone, or **Universal Coordinated Time (UTC)**.
4. Select **Apply**. To close the panel without changing the range, select **Cancel**.

## Edit a dashboard <a href="#edit-a-dashboard" id="edit-a-dashboard"></a>

Select **Edit** to change the dashboard. In edit mode, **Edit** is replaced by **Cancel** and **Save**. Select **Save** to keep your changes, or **Cancel** to discard them.

In edit mode, you can do the following:

* **Rename the dashboard**: Select the pencil icon next to the title or description, and enter the new text.
* **Add a filter**: Select **Add Filter** to create a dashboard filter. Filters appear in the **Dashboard Variables** panel.
* **Add a widget**: Select **New Widget**, then select a widget type. Go to [Add a data widget](#add-a-data-widget) to chart data.
* **Manage a widget**: Select the three-dot menu at the top right of a widget.

The **New Widget** menu has the following widget types:

| Widget type     | What it does                                                                                                                                       |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data Widget** | Opens the widget editor, where you chart data. Go to [Add a data widget](#add-a-data-widget) for details.                                          |
| **Text Widget** | Adds a text field directly to the dashboard layout. Enter your text in the field.                                                                  |
| **Panel**       | Adds an empty panel directly to the dashboard layout, titled **Widget title** until you rename it. To fill the panel, select **Add Widget** in it. |

The widget menu has the following options:

| Option             | What it does                          |
| ------------------ | ------------------------------------- |
| **Edit widget**    | Change the widget configuration.      |
| **Refresh widget** | Reload the data for this widget only. |
| **View Data**      | Show the data behind the widget.      |
| **Clone widget**   | Create a copy of the widget.          |
| **Delete widget**  | Remove the widget from the dashboard. |

## Add a data widget <a href="#add-a-data-widget" id="add-a-data-widget"></a>

A data widget charts data from a query. When you select **New Widget** and then **Data Widget**, the widget editor opens.

![The data widget editor with the Data tab, query settings, and dashboard filters](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-02ccedee8d0146071c1a49ecb5899200afb86ef6%2Fgitops-dashboard-data-widget.png?alt=media)

At the top of the editor, enter a title and optional subtitle, then select the pencil icon to edit either one. Select **Add Widget** to add the widget to the dashboard, or **Cancel** to discard it. To return to the dashboard, select **Back**.

Below the title, the editor has the following controls:

* **Override**: Turn on to set a time range for this widget only. When it is off, the widget uses the dashboard's time range.
* **Visualization type**: Select an icon to choose how the widget displays data. The table view is selected by default.
* **Preview**: Shows the widget output. Until you select a data source, the preview shows **There is no data to display. Add a data source to get started.**

The panel on the right has the **Data** and **Customizations** tabs. The **Data** tab has the following settings under **Query**:

| Setting               | What it does                                                                                                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Code View**         | Turn on to edit the query as code instead of in the form.                                                                                                                                                                 |
| **Data**              | Select **Update data selection** to choose the data that the widget queries. Go to [Choose data for a widget](#choose-data-for-a-widget) for details. Select **Add Table Calculation** to add a calculation to the table. |
| **Dashboard filters** | Choose which dashboard filters change this widget. For **Time Range**, select **Dashboard** to follow the dashboard time range, or **Widget** to select a time field in the widget settings.                              |
| **Widget Filters**    | Select **Add filters** to filter the data for this widget only.                                                                                                                                                           |
| **Sort**              | Select **Add sort** to set the sort order. This setting is required.                                                                                                                                                      |
| **Limit**             | Set the maximum number of rows that the widget returns. This setting is required and defaults to 10.                                                                                                                      |
| **Variables**         | Select **Add Variable** to add a custom variable. **Resolved by dashboard** lists the variables that the dashboard provides. For custom variables, use the `${variableName}` syntax in your query.                        |

### Choose data for a widget <a href="#choose-data-for-a-widget" id="choose-data-for-a-widget"></a>

Select **Update data selection** to open the **Choose data** dialog, where you pick the data sources for the widget and the fields that each source contributes. The following steps use the **GitOps** module as an example. The dialog works the same way for any module.

1. In the **Modules** list on the left, select **GitOps**. The **Sources** list shows the data sources in that module and how many there are. Curated sources have a **Curated** label. The sources are grouped as follows:
   * **Recommended**: **GitOps Applications** and **GitOps Syncs**.
   * **Other sources**: Less-used curated sources, such as **GitOps Agents** and **GitOps Clusters**, and raw sources. Raw sources trade performance for fidelity.
2. To find a source, enter a source or field name in **Search datasources or fields**. Use **All**, **Data source**, and **Data selection** to change what the search covers. To clear the module filter, select the **X** on the module chip.
3. Select a source. A card for the source appears in the **Selections appear here** area on the right. Each source in the join gets its own card, where you choose the fields that it contributes.
4. Select **Confirm** to save the selection, or **Close** to leave without saving.

The **Curated** label marks an official, Harness-managed semantic view. A curated source is pre-modeled, standardized, and recommended for creating widgets.

### Query GitOps data with Code View <a href="#query-gitops-data-with-code-view" id="query-gitops-data-with-code-view"></a>

Use **Code View** to query a GitOps entity directly, such as `gitops:application` or `gitops:appsync`. Code View is the way to query entities that do not have a curated source in the **GitOps** module, such as repositories, and to write queries that the **Choose data** dialog does not cover.

1. In the data widget editor, turn on **Code View** next to **Query**.
2. Enter a query that names the entity and the fields to return.
3. Select **Run Query** to preview the result. The preview does not change until you run the query.
4. Select **Add Widget**.

![The data widget editor with Code View turned on, showing the query editor, Run Query, and Reset to last applied](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-e564d59cde8c2bdb53be79dcd7e4c7dd58661f88%2Fgitops-dashboard-code-view.png?alt=media)

Below the query editor, you can use the following controls:

* **Auto-format on blur**: Turn on to format the query when you click outside the editor. Use the format shortcut shown next to it to format the query at any time.
* **Run Query**: Run the query and update the preview.
* **Reset to last applied**: Discard your edits and return to the last query that you ran.

The following query returns the name, cluster, destination, and creation date of each application, and whether the application is stale:

```
find entity "gitops:application" app
| select {
    app.name,
    app.cluster_identifier,
    app.destination_namespace,
    app.destination_server,
    app.created_at,
    app.stale
  }
```

{% hint style="info" %}
In GitOps application data, `app.stale = true` indicates that the application was deleted in Argo CD. It does not mean that the application is out of sync. To show only active applications, filter on `app.stale == false`.
{% endhint %}

To chart sync operations, replace the entity with `gitops:appsync` and select fields such as `is_pipeline_triggered` and `is_auto_sync`.

## Next steps <a href="#next-steps" id="next-steps"></a>

* [Manage GitOps applications](https://developer.harness.io/continuous-delivery/use-gitops/application/manage-gitops-applications.md): Review the applications that your dashboards show.
* [Sync GitOps applications](https://developer.harness.io/continuous-delivery/use-gitops/application/sync-gitops-applications.md): Understand the sync operations that your dashboards track.
* [GitOps Agents](https://developer.harness.io/continuous-delivery/use-gitops/gitops-entities/agents.md): Review the agents that report GitOps data.

{% @harness-feedback/feedback %}
