The ideal time to automatically run API and web app tests is immediately after a deployment. Using the Assertible deployments API, you can run tests for a web service as part of your continuous-integration or delivery pipeline and track deployments to specific versions of your application.

If the code for your web service is hosted on GitHub, you can also create status checks and deployment events for commits and pull requests.

GitHub logo

Check out our GitHub integration

Deployments API Diagram

The easiest way to create a deployment is to run a simple curl command from your continuous integration pipeline or deployment process:

    "service" : "'"${ASSERTIBLE_SERVICE_ID}"'",
    "environment" : "production",
    "version" : "v1"

See the examples for more examples.


When you post a deployment to Assertible, it's possible to propogate the test statuses and deployment details to GitHub pull requests (and other refs & branches like master).

Assertible GitHub status check

For example, in the picture above, a deployment is created on assertible-staging with a direct link to the staging environment URL using the View deployment button, as well as the status of tests directly in the pull request checks under CircleCI.

Connect your web service to GitHub:

All you need to do to start creating GitHub deployments and status checks is to connect your web service to GitHub and use the github: true parameter in the call to POST /deployments.

When the github: true parameter is used, Assertible posts deployment statuses and test results to the GitHub API for the ref you provide in the deployment script after executing your tests. The ref must be the full SHA1 hash of the commit (don't use the short hash).

Continuous integration services usually populate the environment with a variable containing the commit. For example, CircleCI uses CIRCLE_SHA1. We recommend using the equivalent of $ git rev-parse HEAD.

If you are using Heroku to deploy your code from GitHub, you do not need to manually POST a deployment to Assertible. Heroku will create deployment events for the deployments and Assertible will recieve the events and run your tests. Your web service only needs to be connected to the correct repository.

External GitHub deployment integrations

If you are deploying code using a continuous delivery service like Heroku Pipelines or Heroku Review Apps, deployment events are already posted to the repository for you automatically. See our blog Automate smoke tests for a Go API on Heroku for a more detailed example.

Deployments API examples

Successful request

If the request succeeds, it will respond with the unique id of the deployment:

curl -XPOST -d'{
    "service" : "123e4567-e89b-12d3-a456-426655440000",
    "environment" : "production",
    "version" : "v1.2"


Failed request

If creating the deployment fails, an error will be returned:

curl -XPOST -d'{
    "service" : "123e4567-e89b-12d3-a456-426655440000",
    "environment" : "staging",
    "version" : "v1.2"

{"code":"InvalidRequestError","message":"Cannot parse request body\n\"Error in $: key \\\"service\\\" not present\"\n"}

GitHub deployment

If the request succeeds, it will respond with an empty JSON object:

SHA=$(git rev-parse HEAD)
curl -XPOST -d'{
    "service" : "123e4567-e89b-12d3-a456-426655440000",
    "environment" : "production",
    "version" : "v1",
    "ref" : "'"${SHA}"'",
    "github" : true


These parameters can be used in a request to POST /deployments:

Name Required Description Default
service required The web service/API id. This can be found in the Assertible dashboard under the Deployments tab (look for Bash / Command-line). n/a
version required A unique textual representation of the application version. For example v1.0 or even a commit reference like cc0ab3f. n/a
environment optional Run tests against a specific environment. The environment must match a valid environment for the target web service. See our environments documentation for more information. production
ref optional A unique source control reference or commit hash.
For version control systems like Git, we recommend using the full hash. If you are using the github parameter, make sure that this variable contains the full SHA1 hash, not just a prefix.
Continuous integration services usually populate the environment with a variable containing the commit. For example, CircleCI uses CIRCLE_SHA1. We recommend using the equivalent of $ git rev-parse HEAD.
url optional An external url for viewing further details about the deployment. n/a
github optional If the github parameter is true, Assertible will create deployment events and corresponding status checks for the ref.
Your web service must be connected to a GitHub repository to use this parameter.
tests optional Restrict the test run to a given list of test ids, e.g. "tests" : ["be6df68d-e32f-47c5-bf6f-b1c208182b6f", "f0ca8862-3d29-4b57-910f-efa222dd9aa0"] n/a

If the POST request is made twice, the deployment is updated. This only has an impact for "optional" parameters like ref or url. A unique deployment is represented by the service, environment name, and version combination.

The easiest way to test and
monitor your web services

Define and test your web service with Assertible Track and test API deployments across environments Schedule API monitoring and failure alerts

Reduce bugs in web applications by using Assertible to create an automated QA pipeline that helps you catch failures & ship code faster.

Sign up for free