Get Started with HighTide

Setting up HighTide is quick. This guide walks you through the steps to get up and running:

1. Install the HighTide GitHub App
2. Create and add an authentication token to your CI environment
3. Add a CI step to submit coverage to HighTide
4. Open your first pull request with HighTide enabled

1. Install the HighTide GitHub App

To install the GitHub App:

1. Go to the HighTide GitHub App page.
2. Click "Install".
3. Select the repositories you want to enable HighTide for.
4. Click "Install & Authorize" to start the installation.
5. Review the information and add anything missing.
6. Click "Create" to complete the installation.

Great! You’ve installed the HighTide GitHub App. Next, set up an authentication token so HighTide can receive requests from your CI.

2. Create and add an Authentication Token to your CI environment

HighTide authenticates requests from your CI with a token. Create one and add it to your CI environment:

1. Go to the "Authentication Tokens" page for your account.
2. Click "New Authentication Token".
3. Name it something descriptive, like "CI Token".
4. Click "Create Authentication Token".
5. Copy the generated token and store it securely — you won’t be able to view it again.
6. Add the token to your CI environment as OCTOZOO_TOKEN. See the GitHub Actions guide below, or Contact support if you use a different CI provider and need help.

With your token in place, add a step to your CI pipeline to submit coverage reports to HighTide.

Adding the Authentication Token to GitHub Actions

To add the token to GitHub Actions:

1. Go to your GitHub repository.
2. Open "Settings".
3. Click "Secrets and variables" → "Actions".
4. Click "New repository secret".
5. Set the name to OCTOZOO_TOKEN and paste the value.
6. Click "Add secret" to save.

For more detail, see GitHub's documentation.

Working with Dependabot PRs

To enable HighTide for Dependabot pull requests, create a second authentication token (e.g., "Dependabot Token") and add it under the "Dependabot" secrets section in your repository settings. Name it OCTOZOO_TOKEN as well.

GitHub provides some documentation on why there is a separate section for Dependabot.

3. Add a step to your CI pipeline to submit coverage to HighTide

With your token set, add a CI step that submits coverage reports to HighTide. We provide a CLI that makes this easy: https://www.npmjs.com/package/@octozoo/hightide. It supports JSON coverage formats from tools like Istanbul (JavaScript/TypeScript) and SimpleCov (Ruby). If you use a different tool or need help, please contact support. In the meantime, you can use the custom coverage approach below.

Open a pull request and follow the instructions below for your CI provider and coverage tooling.

GitHub Actions (Supported Coverage Tooling)

Copy the snippet below into your workflow file (usually under .github/workflows/). Replace YOUR_METRIC_ID with the metric ID from the metric’s page in HighTide.

- name: Install hightide CLI
  run: npm install -g @octozoo/hightide

- name: Send line coverage measurements to HighTide
  run: |
    npx @octozoo/hightide submit-coverage --metric YOUR_METRIC_ID
  env:
    OCTOZOO_TOKEN: ${{ secrets.OCTOZOO_TOKEN }}
  

GitHub Actions (Custom Coverage Tooling)

Copy the snippet below into your workflow file (under .github/workflows/). Replace YOUR_METRIC_ID with the metric ID from HighTide. Update the jq commands to parse your coverage report and extract the right values.

- name: Install hightide CLI
  run: npm install -g @octozoo/hightide

- name: Extract covered lines and total lines from your coverage report
  id: extract_coverage
  run: |
    # Replace this with the actual command to extract covered and total lines
    # For example, if you have a JSON report, you might use jq to parse it
    COVERED_LINES=$(jq '.covered_lines' path/to/your/coverage.json)
    TOTAL_LINES=$(jq '.total_lines' path/to/your/coverage.json)
    echo "COVERED_LINES=$COVERED_LINES" >> $GITHUB_ENV
    echo "TOTAL_LINES=$TOTAL_LINES" >> $GITHUB_ENV

- name: Send line coverage measurements to HighTide
  run: |
    npx @octozoo/hightide submit --numerator $COVERED_LINES --denominator $TOTAL_LINES --metric YOUR_METRIC_ID
  env:
    OCTOZOO_TOKEN: ${{ secrets.OCTOZOO_TOKEN }}
  

Please contact support and let us know what tooling you use or if you need help.

Other CI Services (Supported Coverage Tooling)

Here’s a bash script example for submitting coverage. Replace YOUR_METRIC_ID with the metric ID from HighTide.

  #!/bin/bash
  # ... other parts of your CI script

  # Install hightide CLI
  npm install -g @octozoo/hightide

  # Send line coverage measurements to HighTide (assumes OCTOZOO_TOKEN is in your environment)
  npx @octozoo/hightide submit-coverage --metric YOUR_METRIC_ID
  

Please contact support and let us know what CI provider you use or if you need help.

Other CI Services (Custom Coverage Tooling)

Here’s a bash script example for submitting custom coverage values. Replace YOUR_METRIC_ID with the metric ID from HighTide and adapt the extraction commands to your report format.

  #!/bin/bash
  # ... other parts of your CI script

  # Install hightide CLI
  npm install -g @octozoo/hightide

  # Replace this with the actual command to extract covered and total lines
  # For example, if you have a JSON report, you might use jq to parse it
  COVERED_LINES=$(jq '.covered_lines' path/to/your/coverage.json)
  TOTAL_LINES=$(jq '.total_lines' path/to/your/coverage.json)
  # Send line coverage measurements to HighTide (assumes OCTOZOO_TOKEN is in your environment)
  npx @octozoo/hightide submit --numerator "$COVERED_LINES" --denominator "$TOTAL_LINES" --metric YOUR_METRIC_ID
  

Please contact support and let us know what CI and tooling you use or if you need help.

4. Make your first pull request with HighTide enabled

If everything is configured correctly, you’ll see a “Configured Successfully” check on your pull request that adds the CI integration, for example:

Merge your CI configuration pull request. After that, your next pull request will start enforcing coverage.