​
Data Contract Repository

Data contracts are stored in a git repository that you own. Gable requires a new git repository to be created within your organization as the central storage for your data contracts, both to limit exposure of your proprietary code, and to make managing contracts easier.

​
Contracts through Github

Data Contracts can be written, updated, and reviewed using the normal pull request method. See the Data Contract Spec documentation for details on writing a contract. Once contracts are merged into the central contract repository, they can be published into Gable using a CI/CD workflow. Data contracts can be published directly using the gable CLI, but we recommend configuring your contract repo to publish contracts in a CI/CD workflow, and provide out-of-the-box solutions for common CI/CD platforms. Publishing contracts is an idempotent operation! If the contents of a contract file have not been changed, the result is a no-op, so it’s safe to publish all contracts within the central contract repository on every update to the main branch. While the publishing step verifies that a contract is valid before storing it in Gable, we recommend adding a validation step in CI/CD that runs on all all branches to prevent invalid contracts from being merged into the main branch, and to give contract authors immediate feedback of any issues with their proposed contract changes.
  • On push to any branch in the contract repo: validate the contract(s)
  • On push to the main branch: validate the contract(s), and publish the contract(s) to Gable

​
Github Actions

Gable provides two Github Actions to validate and publish contracts. These actions are a convenience wrapper around the Gable Python CLI. Validate Action Publish Action To use the actions, you need to provide the Gable API endpoint for your organization, as well as a valid API key. The API key should be treated as a secret value, and stored accordingly. We recommend using Github’s encrypted secret storage, or the existing secret storage mechanism your organization uses for Github Actions workflows.

​
Gable CLI

Using Gable’s Python CLI, contracts can be validated, updated, and published locally from a developers machine, or as part of a CI/CD workflow that Gable does not yet natively support.

​
Contracts through the Gable console

Existing data contracts can be accessed at https://<your_organization>.gable.ai/contracts. The contract table view displays a list of existing contracts with information on domain, ownership, descriptions, and contract status. From here, you can click into the Contract Detail view to access the contract metadata. This includes the contract description, owner, contract status, enforcement level, schema, and contract specification. Users can edit, delete, and publish contracts through the UI.

​
Creating contracts

To create a contract from scratch, navigate to the Contracts page and click Create Contract in the upper right. You can also click the </> button to generate a YAML contract definition. To create a contract based on an asset, either click the contract icon in the Assets table or navigate to the Asset Details page and click Create Contract in the upper right. The contract definition will be pre-populated based on that asset schema. Fields can be added, edited, and removed. Check an asset’s compliance with the Check asset button.

​
Setting Enforcement Level

Enforcement levels refer to the various tiers of alerts that can be activated when Gable detects potential breaking changes to data assets under contract. These notifications serve to warn individuals that something is either on the verge of breaking or is currently breaking. You can set or update the enforcement level when creating or editing a contract: Enforcement Level Dropdown

​
Enforcement Levels

  • Block - stops the breaking PRs
    • Fail the CI/CD job step (blocking merges if merge checks are also configured), surface the contract violation to subscribers, and comment on the violating PR.
  • Alert - comments on risky PRs
    • Surface the contract violation to subscribers and on Slack, and comment a warning on the violating PR.
  • Notify - sends notifications only
    • Surface the contract violation via Slack.
  • Record - record violations
    • Record the contract violation in the Gable Change Log only.
  • Inactive - disable enforcement
    • Disables contract violation notifications, comments, and merge blocking behavior.

​
Contract lifecycle

  • Draft: Contracts are created via the UI as drafts. Once contract definition is complete, the contract can be published by clicking on the Publish button. Once published, you will see an Active badge by the contract name in the Contracts table and on the contract details page. Contract enforcement will not take effect until the contract is published.
  • Active: Once a contract has been published it is active. At any point, the contract can be Archived or moved back to Draft mode by clicking on the Revert to Draft option from the Manage menu.
  • Archived: If a contract is no longer in use, it can be Archived. Archived contracts will be hidden in the Contracts table by default. If you need to access them, just adjust your filter settings to include archived contracts. To bring an archived contract back, click the Manage button and select Revert to Draft. From there, you can make any necessary changes to the contract before publishing it.

​
Modifying Data Contracts

Similar to [Creating Data Contracts], updating contracts is handled through through your company’s normal PR process. The CI/CD steps set up to publish new contracts will also publish updates to any existing contracts made in a PR. Publishing contracts is an idempotent operation! If the contents of a contract file have not been changed, the result is a no-op, so it’s safe to publish all contracts within the central contract repository on every update to the main branch.