# GitHub Action

The **HostTracker Check** action (`HostTracker/check-action@v1`, on the GitHub Marketplace) runs HostTracker from a
workflow: a one-off check from real monitoring locations, an assertion that every one of them sees the site up, or
the monitors a repository declares in a JSON file. It is a composite action that downloads a pinned,
checksum-verified release of [ht-cli](/integrations/cli/), so there is nothing to install. It runs on Linux, macOS
and Windows runners (amd64 and arm64).

:::note[Plan requirement]
The action uses the API, so your plan must include API access - see
[Rate limits and quotas](/integrations/rate-limits/#which-plans-include-the-api).
:::

## Before you start

1. Mint an API token under **Integrations -> API** (`/integrations/api`) with the scopes for the mode you use:
   - `check` and `assert-up` modes: `check:read` and `check:write` (or the `check` family).
   - `create-monitor` mode: `monitor:read` and `monitor:write`.
2. In your repository, add it as an Actions secret, for example `HT_TOKEN` (Settings -> Secrets and variables ->
   Actions).

## Inputs

| Input | Required | Default | What it does |
|---|---|---|---|
| `token` | yes | - | The API token. Pass it from a secret: `${{ secrets.HT_TOKEN }}`. |
| `mode` | no | `check` | `check` (run one check and report), `assert-up` (fail the step unless every location sees the site up), `create-monitor` (create monitors from `json`). |
| `url` | for `check` / `assert-up` | - | The address to check. |
| `type` | no | `http` | The instant-check type. |
| `pools` | no | - | Comma-separated location pool ids, for example `westeurope,northamerica` (there is no single `europe` pool). The ids: [Monitoring locations](/reference/locations/#common-pool-ids). |
| `json` | for `create-monitor` | - | The monitor definitions your repository declares (see the action's [README](https://github.com/HostTracker/check-action) for the accepted form). |
| `timeout` | no | `120` | How long to wait for results, in seconds. |
| `fail-on-down` | no | `true` | Fail the step when the check comes back down. |
| `base-url` | no | `https://api2.host-tracker.com` | The API root. |
| `version` | no | the pinned ht-cli release | The ht-cli version to download, or `latest`. |

## Outputs

| Output | What it holds |
|---|---|
| `state` | The overall result state. |
| `result-json` | The full result as JSON, for later steps to parse. |
| `monitor-id` | The monitor's id (`create-monitor` mode). |
| `summary` | A short human-readable summary. |

## Examples

**Gate a deploy: every location must see the site up.**

```yaml
- name: The deployed site answers, everywhere
  uses: HostTracker/check-action@v1
  with:
    token: ${{ secrets.HT_TOKEN }}
    mode: assert-up
    url: https://staging.example.com
    pools: westeurope,northamerica
```

**Run a check and use its result later in the job.**

```yaml
- name: HostTracker check
  id: ht
  uses: HostTracker/check-action@v1
  with:
    token: ${{ secrets.HT_TOKEN }}
    url: https://www.example.com
    fail-on-down: false

- run: echo "State was ${{ steps.ht.outputs.state }} - ${{ steps.ht.outputs.summary }}"
```

**Keep monitors in the repository.** In `create-monitor` mode the action creates the monitors your repository
declares in JSON (passed through the `json` input). It looks for an existing monitor with the same url and name
first, so re-running the workflow does not create duplicates.

A monitor definition uses the API's create body - see [REST API v2](/integrations/rest-api/) and the
[monitor settings reference](/reference/monitor-settings/). For full lifecycle management (changes and deletions),
the [Terraform provider](/integrations/terraform/) is the better tool.

## Versions

`@v1` follows the latest 1.x release. Pin `@v1.2.3` or a commit SHA for exact control. A breaking change will be a
new major version (`@v2`), and `@v1` stays where it is.

## What it costs

An instant check counts against the `check` scope's API quota; creating a monitor uses one of your plan's monitor
slots. See [Rate limits and quotas](/integrations/rate-limits/).

## Related

- [ht-cli](/integrations/cli/)
- [REST API v2](/integrations/rest-api/)
- [API authentication, tokens and scopes](/integrations/api-authentication/)
- [Instant checks vs monitors](/getting-started/instant-checks-vs-monitors/)