Skip to content
HostTracker Docs

GitHub Action

View as Markdown

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, so there is nothing to install. It runs on Linux, macOS and Windows runners (amd64 and arm64).

Before you start

Section titled “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

Section titled “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.
json for create-monitor - The monitor definitions your repository declares (see the action’s README 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

Section titled “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

Section titled “Examples”

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

- 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.

- 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 and the monitor settings reference. For full lifecycle management (changes and deletions), the Terraform provider is the better tool.

Versions

Section titled “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

Section titled “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.

Section titled “Related”