> 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-integration/use-harness-ci/use-harness-ci/run-tests/test-management/ci-test-policies.md).

# Test Policies

Automate test management with rules that run after each pipeline execution

{% hint style="info" %}
**PREREQUISITES**

Test Policies require the feature flag `TI_POLICY_EVALUATION_ENABLED` to be enabled on your account. To use hcli commands for managing test policies, you must also set the environment variable `CI_ENABLE_HCLI_FOR_TESTS=true` in your pipeline.

Contact [Harness Support](mailto:support@harness.io) to enable the feature flag. Go to [Environment variables](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md#environment-variables) to configure environment variables.
{% endhint %}

## Test Policies <a href="#test-policies" id="test-policies"></a>

Policies automate test management. Configure rules once, and Harness evaluates with every pipeline execution, automatically marking flaky tests or quarantining failures without manual intervention.

{% hint style="info" %}
**WHO MANAGES POLICIES?**

Policies are typically configured by **platform engineers or QA leads**—not individual developers. This separation ensures quality gates can't be bypassed. Administrators run policy commands locally or from a secure pipeline, while developers simply run their tests.
{% endhint %}

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before using test policy commands, ensure you have:

* **Harness account access:** Account, organization, and project IDs.
* **Personal Access Token (PAT):** Required for API authentication. Go to [Manage API keys](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md) to create a PAT.
* **hcli installed:** Harness CLI tool must be available in your environment. Go to [Install and configure Harness CLI](/harness-ai/use-harness-platform/automation/cli/install.md) to download hcli for your operating system and architecture.

***

### Quick Start <a href="#quick-start" id="quick-start"></a>

Create a policy that auto-quarantines any failing test:

```bash
# 1. Create policy file <a href="#1-create-policy-file" id="1-create-policy-file"></a>
cat > policies.json << 'EOF'
[
  {
    "when": ["test failed"],
    "action": ["mark quarantine"]
  }
]
EOF

# 2. Apply to repository <a href="#2-apply-to-repository" id="2-apply-to-repository"></a>
hcli test-management policy set \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --org-id="$HARNESS_ORG_ID" \
  --project-id="$HARNESS_PROJECT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT" \
  --file=policies.json
```

{% hint style="info" %}
**REPOSITORY URL FORMAT**

The `.git` suffix is optional. If omitted, it will be appended automatically.
{% endhint %}

{% hint style="info" %}
**ENDPOINT VARIES BY INSTANCE**

The `--endpoint` value is based on your Harness instance domain: `https://<your-instance>/gateway/ti-service/`

For example, if you access Harness at `https://your-instance.harness.io`, use `https://your-instance.harness.io/gateway/ti-service/`.
{% endhint %}

### Policy Format <a href="#policy-format" id="policy-format"></a>

```json
[
  {
    "when": ["condition"],
    "action": ["action"]
  }
]
```

| Field    | Description                                       |
| -------- | ------------------------------------------------- |
| `when`   | Array of conditions (all must match—AND logic)    |
| `action` | Array of actions to execute when conditions match |

You can define up to **10 policies** per repository.

### Available Conditions <a href="#available-conditions" id="available-conditions"></a>

| Condition       | Scope             | Description                            |
| --------------- | ----------------- | -------------------------------------- |
| `test failed`   | Current execution | Test failed in this pipeline run       |
| `test is flaky` | Historical        | Test was previously detected as flaky  |
| `test is slow`  | Current execution | Test execution time exceeded threshold |

### Available Actions <a href="#available-actions" id="available-actions"></a>

| Action              | Effect                                                                            |
| ------------------- | --------------------------------------------------------------------------------- |
| `mark flaky`        | Force test as flaky (overrides auto-detection)                                    |
| `unmark flaky`      | Clear any manual override—let auto-detection decide flaky status                  |
| `mark unflaky`      | Force test as stable—ignores auto-detection even if test behavior is inconsistent |
| `mark quarantine`   | Quarantine the test—failures won't block pipeline                                 |
| `unmark quarantine` | Remove from quarantine                                                            |

{% hint style="info" %}
**FLAKY STATUS IS TRI-STATE**

A test's flaky status has three possible values:

* **true** (flaky): Set by `mark flaky` or auto-detection
* **false** (stable): Set by `mark unflaky`—overrides detection
* **unset** (auto): Set by `unmark flaky`—lets detection decide
  {% endhint %}

### Policy Examples <a href="#policy-examples" id="policy-examples"></a>

#### Auto-Quarantine Failing Tests <a href="#auto-quarantine-failing-tests" id="auto-quarantine-failing-tests"></a>

Immediately quarantine any test that fails:

```json
[
  {
    "when": ["test failed"],
    "action": ["mark quarantine"]
  }
]
```

#### Mark Slow Tests as Flaky <a href="#mark-slow-tests-as-flaky" id="mark-slow-tests-as-flaky"></a>

Flag tests with timing issues:

```json
[
  {
    "when": ["test is slow"],
    "action": ["mark flaky"]
  }
]
```

#### Quarantine Flaky Failures <a href="#quarantine-flaky-failures" id="quarantine-flaky-failures"></a>

Only quarantine tests that are already flaky AND fail:

```json
[
  {
    "when": ["test is flaky", "test failed"],
    "action": ["mark quarantine"]
  }
]
```

{% hint style="warning" %}
**POLICY ORDER MATTERS**

Policies are evaluated in order. Place quarantine rules before flaky rules when combining conditions. If a test is marked flaky by an earlier policy, a later policy checking `test is flaky` will match.
{% endhint %}

### View Current Policies <a href="#view-current-policies" id="view-current-policies"></a>

```bash
hcli test-management policy get \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT"
```

#### Required Parameters <a href="#required-parameters" id="required-parameters"></a>

* `--account-id`: Your Harness account ID
* `--repo`: Repository URL (with or without `.git` suffix)
* `--endpoint`: TI service endpoint URL
* `--api-key`: Your Personal Access Token (PAT) starting with `pat.`

#### Optional Parameters <a href="#optional-parameters" id="optional-parameters"></a>

* `--org-id`: Organization ID (filters policies to a specific organization)
* `--project-id`: Project ID (filters policies to a specific project)

Example output:

```
Found 1 policy(ies):
[
  {
    "when": ["test failed"],
    "action": ["mark quarantine"]
  }
]
```

### Update Policies <a href="#update-policies" id="update-policies"></a>

`policy set` **replaces all policies**. Always include every policy you want active:

```bash
# Add a new policy to existing ones <a href="#add-a-new-policy-to-existing-ones" id="add-a-new-policy-to-existing-ones"></a>
cat > policies.json << 'EOF'
[
  {
    "when": ["test failed"],
    "action": ["mark quarantine"]
  },
  {
    "when": ["test is slow"],
    "action": ["mark flaky"]
  }
]
EOF

hcli test-management policy set \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --org-id="$HARNESS_ORG_ID" \
  --project-id="$HARNESS_PROJECT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT" \
  --file=policies.json
```

### Clear All Policies <a href="#clear-all-policies" id="clear-all-policies"></a>

```bash
echo '[]' | hcli test-management policy set \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --org-id="$HARNESS_ORG_ID" \
  --project-id="$HARNESS_PROJECT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT" \
  --file=-
```

### Running hcli Locally vs In Pipelines <a href="#running-hcli-locally-vs-in-pipelines" id="running-hcli-locally-vs-in-pipelines"></a>

#### In Harness Pipelines <a href="#in-harness-pipelines" id="in-harness-pipelines"></a>

Most environment variables are automatically available:

```bash
hcli test-management policy get \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --org-id="$HARNESS_ORG_ID" \
  --project-id="$HARNESS_PROJECT_ID" \
  --repo="$DRONE_GIT_HTTP_URL" \
  --endpoint="$HARNESS_TI_SERVICE_ENDPOINT" \
  --api-key="<+secrets.getValue('harness_pat')>"
```

{% hint style="info" %}
**ENDPOINT CONFIGURATION**

The `HARNESS_TI_SERVICE_ENDPOINT` environment variable is automatically configured based on your cluster. For self-managed installations or custom endpoints, go to [Configure OIDC with GCP WIF for Harness Cloud builds](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#how-do-i-configure-oidc-with-gcp-wif-for-harness-cloud-builds) to understand endpoint configuration.
{% endhint %}

{% hint style="info" %}
**STORE PAT AS A SECRET**

Store your Personal Access Token in Harness Secrets Manager and reference it using the expression syntax shown above. Never hardcode tokens in pipeline YAML.
{% endhint %}

#### Running Locally (Administrators) <a href="#running-locally-administrators" id="running-locally-administrators"></a>

You must provide all parameters explicitly:

```bash
hcli test-management policy set \
  --account-id="px7xd_BFRCi-pfWPYXVjvw" \
  --org-id="default" \
  --project-id="my-project" \
  --repo="https://github.com/my-org/my-repo" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="pat.ACCOUNT_ID.RANDOM_STRING.TOKEN_VALUE" \
  --file=policies.json
```

### CLI Reference <a href="#cli-reference" id="cli-reference"></a>

#### policy set <a href="#policy-set" id="policy-set"></a>

| Parameter      | Required | Description                                            |
| -------------- | -------- | ------------------------------------------------------ |
| `--account-id` | Yes      | Harness account ID                                     |
| `--org-id`     | Yes      | Organization ID                                        |
| `--project-id` | Yes      | Project ID                                             |
| `--repo`       | Yes      | Repository URL (`.git` suffix optional, auto-appended) |
| `--endpoint`   | Yes      | TI service endpoint URL                                |
| `--api-key`    | Yes      | Personal Access Token (PAT) starting with `pat.`       |
| `--file`       | Yes      | Path to JSON file (use `-` for stdin)                  |

#### policy get <a href="#policy-get" id="policy-get"></a>

| Parameter      | Required | Description                                            |
| -------------- | -------- | ------------------------------------------------------ |
| `--account-id` | Yes      | Harness account ID                                     |
| `--repo`       | Yes      | Repository URL (`.git` suffix optional, auto-appended) |
| `--endpoint`   | Yes      | TI service endpoint URL                                |
| `--api-key`    | Yes      | Personal Access Token (PAT) starting with `pat.`       |
| `--org-id`     | No       | Organization ID (filters results to specific org)      |
| `--project-id` | No       | Project ID (filters results to specific project)       |

### Best Practices <a href="#best-practices" id="best-practices"></a>

| Practice                      | Why                                            |
| ----------------------------- | ---------------------------------------------- |
| Version control your policies | Track changes, enable code review              |
| Start conservative            | Begin with lenient policies, tighten as needed |
| Review policy effects weekly  | Ensure policies aren't over-quarantining       |
| Document policy rationale     | Help future admins understand intent           |

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

* [View quarantined tests](/continuous-integration/use-harness-ci/use-harness-ci/run-tests/test-management/ci-test-quarantine.md) affected by policies
* [View flaky tests](/continuous-integration/use-harness-ci/use-harness-ci/run-tests/test-management/ci-flaky-tests.md) detected by the system

{% @harness-feedback/feedback %}