boltZharp Docs
rocket_launchMonitors

CI/CD Pipelines

Get told when a build or deploy fails, hangs or is fixed — and see every deploy next to your incidents.

A CI/CD pipeline monitor watches one pipeline: a GitHub Actions workflow, a GitLab CI project, or any CI that can call a URL — Jenkins, CircleCI, Bitbucket Pipelines, Azure Pipelines and others. Every run is kept on the monitor's page. A run that fails or gets stuck on the branch you watch opens an incident, which alerts the people, channels and escalation policy on the monitor like any other; the next green run closes it. Passing runs on that branch are recorded as deploys, so an incident that starts shortly after one says so.

Create a pipeline monitor

  1. 1
    Pick the type

    On the Monitors page click New, open Monitor type and choose CI/CD pipeline monitor.

  2. 2
    Choose where it runs

    Under Runs on, pick GitHub Actions, GitLab CI or Any CI, by webhook. For GitHub and GitLab, choose the Repository and, on GitHub, the Workflow (or Every workflow). For the webhook, copy the Webhook URL — see Any CI, by webhook.

  3. 3
    Set the branch

    Branch is the branch that alerts, main unless you change it. Runs on other branches and pull requests show in the history but never open an incident.

  4. 4
    Save

    Click Create monitor. What alerts is under Advanced settings → Alert me when — see Alerts.

GitHub Actions

Runs arrive through the Zharp AI GitHub app you connected under Integrations → Code; nothing is added to the repository. The app needs read access to Actions. If you installed it before CI/CD monitors existed, GitHub asks the organisation owner to approve that permission — until then the form says Zharp can't see the repository's Actions.

  • Each workflow run reports when it starts and when it completes. A re-run is recorded as a run of its own.
  • When a run fails, Zharp reads which job and step failed and keeps the end of that job's log.
  • Every 10 minutes Zharp also compares recent runs with what it has, so a delivery GitHub never made isn't missed.

GitLab CI

Runs come through your GitLab connection under Integrations → Code. When you save the monitor, Zharp adds a project webhook for pipeline events to the repository, and removes it when the monitor is deleted.

info
Without Maintainer rights

Adding a webhook needs the Maintainer role on the project. With less, the monitor checks the project's pipelines every minute instead — alerts can then be up to a minute later. A self-managed GitLab that can't reach api.zharp.io works the same way.

Any CI, by webhook

Each pipeline monitor has its own URL, https://api.zharp.io/api/v1/ci/<token>. The token is the credential, so store the URL as a secret in your CI. Call it when a run ends — and, if you can, when it starts: that times the run and lets Zharp notice one that hangs.

URLWhat it records
POST /ci/<token>/startA run has started.
POST /ci/<token>/finishA run has ended. Without a status it counts as passed.
POST /ci/<token>A start or an end, as its status says.

Fields

Send them as form fields, JSON or query parameters. Zharp also understands the names each CI uses for them, such as BUILD_NUMBER, GIT_BRANCH or CIRCLE_SHA1, so you can pass a CI's variables straight through.

FieldMeaning
statusHow the run ended: success, failure, cancelled or timed_out — or a start, started. Jenkins' SUCCESS/FAILURE/ABORTED, GitHub's and Azure's words and an exit_code work too.
runThe run's id in your CI. A start and its end must send the same one.
branchThe branch. refs/heads/ and origin/ are removed.
commit, message, authorThe commit and who pushed it, shown in alerts and the history.
urlA link to the run, for the alert's button.
stepWhere a failed run stopped.
logThe end of the log; the last 4,000 characters are kept, colour codes removed.
durationHow long it took — seconds, or like 4m 51s. Measured for you when you sent a start.
deployfalse when a passing run didn't deploy anything. Every passing run on the watched branch counts as a deploy otherwise.

Responses

  • 200 — recorded. A second end for the same run answers 200 and changes nothing.
  • 400 — the call didn't say what happened (no status, and no /start or /finish).
  • 404 — no CI/CD monitor has that token.

A paused monitor answers 200 and records nothing.

Examples

Jenkins
// Jenkinsfile — save the webhook URL as the secret text credential ZHARP_CI_URL
pipeline {
  agent any
  environment { ZHARP_CI_URL = credentials('ZHARP_CI_URL') }
  stages {
    stage('Start') { steps { sh 'curl -fsS -X POST "$ZHARP_CI_URL/start" -d run=$BUILD_NUMBER -d branch=$GIT_BRANCH' } }
    // … your stages …
  }
  post {
    always {
      sh """curl -fsS -X POST \$ZHARP_CI_URL \\
        -d status=${currentBuild.currentResult} \\
        -d run=${BUILD_NUMBER} -d url=${BUILD_URL} \\
        -d branch=${GIT_BRANCH} -d commit=${GIT_COMMIT}"""
    }
  }
}
CircleCI
# .circleci/config.yml — last steps of the job; ZHARP_CI_URL is a project environment variable
- run:
    name: Tell Zharp it passed
    when: on_success
    command: curl -fsS -X POST "$ZHARP_CI_URL" -d status=success -d run=$CIRCLE_BUILD_NUM -d branch=$CIRCLE_BRANCH -d commit=$CIRCLE_SHA1 -d url=$CIRCLE_BUILD_URL
- run:
    name: Tell Zharp it failed
    when: on_fail
    command: curl -fsS -X POST "$ZHARP_CI_URL" -d status=failure -d run=$CIRCLE_BUILD_NUM -d branch=$CIRCLE_BRANCH -d commit=$CIRCLE_SHA1 -d url=$CIRCLE_BUILD_URL
Bitbucket Pipelines
# bitbucket-pipelines.yml — inside the step; ZHARP_CI_URL is a secured repository variable
after-script:
  - curl -fsS -X POST "$ZHARP_CI_URL" -d exit_code=$BITBUCKET_EXIT_CODE -d run=$BITBUCKET_BUILD_NUMBER -d branch=$BITBUCKET_BRANCH -d commit=$BITBUCKET_COMMIT
Azure Pipelines
# azure-pipelines.yml — the last step; ZHARP_CI_URL is a secret pipeline variable
- script: curl -fsS -X POST "$(ZHARP_CI_URL)" -d status=$(Agent.JobStatus) -d run=$(Build.BuildId) -d branch=$(Build.SourceBranch) -d commit=$(Build.SourceVersion)
  condition: always()
Any CI, with curl
# When the run starts (optional — it times the run and powers the stuck check)
curl -fsS -X POST https://api.zharp.io/api/v1/ci/YOUR_TOKEN/start -d run=1234 -d branch=main

# When it ends
curl -fsS -X POST https://api.zharp.io/api/v1/ci/YOUR_TOKEN \
  -d run=1234 -d status=failure -d branch=main \
  -d commit=a91f3c2 -d message="Bump stripe-node to 14.2" -d author="Ama Owusu" \
  -d step="test › Run unit tests" -d url=https://ci.example.com/runs/1234 \
  --data-urlencode log@test-output.txt

Alerts

Under Advanced settings → Alert me when:

SwitchWhenDefault
A build failsA run on the watched branch fails or times out. An incident opens.On
A build is stuckA run on the watched branch is still going at 3× its usual time (never under 10 minutes), or after 45 minutes. An incident opens at high urgency.On
It’s fixedThe next passing run after a failure. The incident resolves either way; off, nobody is told.On
A deploy startsA run on the watched branch starts. A notice to the monitor's connections and followers.Off
A deploy finishesA run on the watched branch passes. A notice with the commit and who shipped it.Off

The usual time is the median of the last passing runs on the branch. Deploy notices go to the monitor's connections (Slack, Teams, a webhook…) and to the people following it, by their own e-mail and push settings — never through an escalation policy, and never to PagerDuty or Opsgenie. Webhooks receive the events deploy.failed, deploy.stuck, deploy.fixed, deploy.started and deploy.finished.

The monitor's page

  • How often the branch passes over 30 days, its usual run time, the last deploy and this week's deploys.
  • The last 40 runs as a chart: height is how long each took, colour how it ended.
  • Every run, on every branch. A running one spins; a failed one opens to the step it stopped at and its log, with Ask Zharp AI why.
  • After a deploy: the latest incident, on any monitor, that started within an hour after one of its deploys.

Deploys on incidents

An incident's timeline lists, under Changes, each deploy from two hours before it started: the pipeline, the commit, who shipped it and how many minutes before it began. Zharp AI reads the same list when it investigates an incident, and looks at the closest deploy first.