Skip to main content

​
Purpose

This guide will help your team register data assets, author and publish Data Contracts, and enforce those contracts pre-merge using Gable’s CLI and CI/CD integrations. By the end of this process, you’ll have:
  • A production environment ready for contract enforcement
  • Your first Data Contract defined and published
  • Confidence that breaking changes will be detected before code is merged

​
Prerequisites

  • TypeScript service that emits data
    • What project/repo(s) do you want to run on?
    • What data flows out of your service or application do you want to put contracts on?
  • Access to relevant GitHub or GitLab repositories for code scanning
  • [Bonus] Slack channel for alerts

​
Access

  1. Once the prod environment is ready, you’ll receive email invites
  2. Log in to your Gable environment
  3. Once logged in, you can add more users by going to Settings > Users > Invite User.

​
Register relevant assets

First, register the code paths that emit data in your TypeScript application.
  1. Identify the data flow patterns and points of interest that you’d like to put contracts on. Gable natively supports some common event publishing libraries like Segment & Amplitude.
    1. If you are interested in patterns that are not currently supported, share those patterns with the Gable team and we will register them with our static analysis engine.
    2. You can also register an asset based on function parameter or key.
  2. In your project root, run the appropriate gable data-asset register command. You can find examples here.
  3. Verify in the CLI output that assets have been registered successfully.

​
Create your first contract

  1. Go to the Gable Dashboard and access Assets in the left hand nav.
  2. Select the asset you want to put a contract on.
  3. Select Create contract in the upper right
    1. Add a Name, Domain, and Description for your contract.
  4. The schema and type definition will be populated automatically based on the static analysis of the code during asset registration. Review the schema and make any desired changes. You can also restrict PII in the asset by checking the Restrict PII checkbox above the schema definition.
    1. Click Check asset to see whether asset violates the contract.
  5. Select an Enforcement Level for the contract. We recommend setting the Enforcement Level to Alert in order to warn on risky PRs.
  6. Save the contract.

​
Integrate Gable into your CI/CD

  1. Add the GABLE_API_KEY as a secret in your repo (e.g. GitHub Secrets).
  2. Access the GABLE_API_ENDPOINT from Settings > API > API Endpoint.
  3. Configure a Github Action with the same data-asset-options as the gable data-asset register command used above.
jobs:
  check-typescript-assets:
    runs-on: ubuntu-latest
    name: "Check Typescript Data Assets"
    steps:
      - name: Check Data Assets
        uses: gabledata/cicd/github-actions/check-data-assets@latest
        with:
          gable-api-key: ${{secrets.GABLE_API_KEY}}
          gable-api-endpoint: ${{vars.GABLE_API_ENDPOINT}}
          data-asset-options: |
            --source-type typescript \
            --project-root . \
            --library segment

​
[Bonus] Set up notifications for contract violations

  1. In the Gable Dashboard, go to Actions > Create an Action.
  2. Select the project as the Asset Origin and under Change Event select “Contract violation”.
  3. Select Create Action and fill in Action Name, e.g. “Contract violation”.
  4. Set a destination, e.g. a team (or dedicated Gable alert) Slack channel.
    1. To connect Slack, go to Settings > Slack.

​
How to test

  1. Follow the steps above to register assets, create a contract, and integrate Gable into your CI/CD.
  2. Make a code change that should violate an existing contract.
  3. Open a pull request.
  4. View Gable notification in Github on the PR.
⌘I