Where Observability
meets Structure

The only observability tool to build API behaviour models, Akita enables API-centric system monitoring and allows users to automatically detect breaking changes.

More about how Akita works

Integrate with CI/CD

Add Akita to your CI/CD and integrate with source control.

You can run Akita on every pull request to get alerts about:

  • Removed, added, and modified API endpoints
  • Removed, added, and modified fields
  • Changes to types and data formats
  • ๐Ÿšง Coming soon: implicit contracts

There are two parts to running Akita on every pull request:

  1. Add the Akita agent to a CI/CD Pipeline. The first step is to give Akita visibility into your CI/CD traffic. Follow the instructions below to get up Akita running with your CI/CD setup. This will set up Akita to run whenever pull requests happen.
  2. Give Akita permissions to post comments to source control. The next step is to give Akita the ability to post comments to your GitHub or GitLab so it can post API diffs.

To run Akita in a CI/CD pipeline, add two additional stages to your pipeline, one to start Akita and another to stop Akita.

In this guide, we will cover:

Use Akita in CI with GitHub integration.

Native Client

Akita supports CircleCI and Travis out of the box. You can simply start a learning session before your API tests run and stop the learning session once your test complete.

Docker Client

In order to use the docker client, you will need to propagate a few CI environment into the docker container. Below are examples for CircleCI and Travis.

docker pull akitasoftware/cli:latest && docker run --rm -d \
  --env CI \
  --env CIRCLECI \
  --env CIRCLE_REPOSITORY_URL \
  --env CIRCLE_BRANCH \
  --env CIRCLE_SHA1 \
  --env CIRCLE_PULL_REQUEST \
  --env CIRCLE_BUILD_URL \
  --env AKITA_API_KEY_ID \
  --env AKITA_API_KEY_SECRET \
  --net {NET} \
  --name akita \
  akitasoftware/cli:latest learn \
  --service {SERVICE} \
  --filter "port {PORT}"
docker pull akitasoftware/cli:latest && docker run --rm -d \
  --env CI \
  --env TRAVIS \
  --env TRAVIS_REPO_SLUG \
  --env TRAVIS_BRANCH \
  --env TRAVIS_COMMIT \
  --env TRAVIS_PULL_REQUEST \
  --env TRAVIS_BUILD_WEB_URL \
  --env TRAVIS_JOB_WEB_URL \
  --env AKITA_API_KEY_ID \
  --env AKITA_API_KEY_SECRET \
  --net {NET} \
  --name akita \
  akitasoftware/cli:latest learn
  --service {SERVICE} \
  --filter "port {PORT}"

Other CI/CD Pipelines

Not using CircleCI or Travis? No problem! You can manually configure the Akita client with information on GitHub PR using command line flags.

docker pull akitasoftware/cli:latest && docker run --rm -d \
  --env AKITA_API_KEY_ID=${AKITA_API_KEY_ID} \
  --env AKITA_API_KEY_SECRET=${AKITA_API_KEY_SECRET} \
  --net {NET} \
  --name akita \
  akitasoftware/cli:latest learn \
  --github-repo {REPO_NAME} \
  --github-pr {GITHUB_PR_NUM} \
  --github-commit {SHA} \
  --github-branch {BRANCH_NAME} \
  --service {SERVICE} \
  --filter "port {PORT}"

Use Akita in CI with GitLab integration.

Integrating with GitLab is easy. All you need to do is supply the following information to the akita client:

  • Project ID
  • Merge Request IID (id vs iid)
  • Git branch name
  • Git commit hash

For instance:

docker pull akitasoftware/cli:latest && docker run --rm -d \
  --env AKITA_API_KEY_ID=${AKITA_API_KEY_ID} \
  --env AKITA_API_KEY_SECRET=${AKITA_API_KEY_SECRET} \
  --net {NET} \
  --name akita \
  akitasoftware/cli:latest learn \
  --gitlab-project {GITLAB_PROJECT_ID} \
  --gitlab-mr {GITLAB_MERGE_REQUEST_IID} \
  --gitlab-commit {SHA} \
  --gitlab-branch {BRANCH_NAME} \
  --service {SERVICE} \
  --filter "port {PORT}"

How to run the Akita Client on CircleCI with GitHub Integration (Example)

For illustration purposes, we have provided examples of what those additional stages would look like in a CircleCI pipeline. Adapting these for other CI/CD pipelines should be simple. In this implementation, we are relying on docker to ensure maximum portability across environments.

Start Akita

In the example, we are starting Akita to learn from a service running within a container. This same command can monitor services not running in containers using replacing --net=container:{CONTAINER} with --net=host.

run_akita:
  description: Start Akita to generate API Specifications
  steps:
    - run:
        name: Run Akita
        command: | 
                docker run --rm -d \
                      --env CI="${CI}" \
                      --env CIRCLECI="${CIRCLECI}" \
                      --env CIRCLE_REPOSITORY_URL="${CIRCLE_REPOSITORY_URL}" \
                      --env CIRCLE_BRANCH="${CIRCLE_BRANCH}" \
                      --env CIRCLE_SHA1="${CIRCLE_SHA1}" \
                      --env CIRCLE_PULL_REQUEST="${CIRCLE_PULL_REQUEST}" \
                      --env CIRCLE_BUILD_URL="${CIRCLE_BUILD_URL}" \
                      --env AKITA_API_KEY_ID=${AKITA_API_KEY_ID} \
                      --env AKITA_API_KEY_SECRET=${AKITA_API_KEY_SECRET} \
                      --net {NET} \
                      --name akita \
                      akitasoftware/cli:latest learn \
                      --service {SERVICE} \
                      --filter "port {PORT}"
        background: true

Stopping Akita

Stopping the Akita service is simple, simply send the SIGINT signal using the docker kill subcommand.

stop_akita:
  description: Stop Akita after tests have completed
  steps:
    - run:
        name: Stop Akita
        command: docker kill --signal=SIGINT akita

Updating the 'STABLE' version

Akita detects differences in your API by comparing the API model from your pull request with an API model previously marked as STABLE. Typically, this is a model built from the most recent commit on the main branch and is updated when the main branch changes.

There are two ways to update the STABLE version: manually or as part of CI.

Updating manually

Use the akita setversion command to update the version manually. You will need to know the Akita URI of the spec to mark as stable.

akita setversion stable akita://your_service:spec:your_spec

Alternatively, you can update the stable version on your service's page in the Akita UI.

Updating as part of CircleCI

CircleCI will ensure that the main branch will build and pass integration tests after each PR is merged. Using the environment variables set by CircleCI, you can selectively enable Akita to run post-merge and assign the STABLE version to the resulting spec.

Here's an example of a Bash script for running Akita with CircleCI. In this scenario, CircleCI invokes the script.

if [ "${CIRCLECI:-false}" = true ] && [ "${CIRCLE_BRANCH:-x}" = "master" ]; then
  # If CircleCI is running on our main branch, then run Akita and
  # mark the resulting spec as the stable version.
  echo "Running Akita to update the stable version..."
  docker run --rm -d \
    --env CI \
    --env CIRCLECI \
    --env CIRCLE_REPOSITORY_URL \
    --env CIRCLE_BRANCH \
    --env CIRCLE_SHA1 \
    --env CIRCLE_BUILD_URL \
    --env AKITA_API_KEY_ID \
    --env AKITA_API_KEY_SECRET \
    # Be sure to connect the container to your service's Docker network
    --net container:local_service \
    akitasoftware:cli/latest \
      learn \
      --service your_service \
      --filter "port 80" \
      --versions stable
fi

The key elements are:

  • Line 1 tests the CIRCLECI and CIRCLE_BRANCH environment variables to see that this is a CircleCI run on the main branch, not a pull request branch.
  • Line 21 adds the --versions stable flag to mark the model being built as STABLE.

Updating as part of other CI frameworks

Different CI frameworks handle merged PRs differently. We have confirmed that CircleCI can be used to automatically update the STABLE version. For this approach to work, your CI framework must

  1. build and run your integration tests on your main branch after each PR is merged
  2. provide environment variables or the equivalent to indicate whether a given CI run is on a PR branch or on the main branch -- you'll need to test these to determine whether to include the --versions stable flag on the Akita CLI to update the STABLE version.

Updated 2 months ago


What's Next

Give Akita permissions to post comments!

Integrate with GitHub
Integrate with GitLab

Integrate with CI/CD


Add Akita to your CI/CD and integrate with source control.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.