Quickstart guide

From zero to your first dependency check in under 15 minutes.

Prerequisites

A Buildpathio account — sign up free
At least one service repo on GitHub or GitLab
The ability to push a workflow file or run a CLI tool in CI

Step 1: Create a workspace

After signing in, create a new workspace for your organization. Each workspace has a unique API token you'll use when submitting manifests.

Your API token is scoped to a single workspace. Teams with multiple platforms (e.g. monorepo + separate mobile services) typically use separate workspaces.

Step 2: Push your first manifest

A manifest describes one service: its name, version, the contracts it exposes, and the services it depends on. Push it with a single API call from CI:

terminal — push manifest

$ curl -X POST https://api.buildpathio.com/v1/manifests \
  -H "Authorization: Bearer $BUILDPATH_TOKEN" \
  -H "Content-Type: application/json" \
  -d @buildpath-manifest.json
201 Created
{"manifest_id": "mfst_8kZ3p", "service": "order-service", "version": "1.4.2"}

Step 3: Define your manifest file

Create buildpath-manifest.json in the root of each service repo:

buildpath-manifest.json

{
  "service": "order-service",
  "version": "1.4.2",
  "team": "fulfillment",
  "contracts": [
    {"type": "http", "path": "/v1/orders", "method": "POST"},
    {"type": "http", "path": "/v1/orders/{id}", "method": "GET"}
  ],
  "dependencies": [
    {"service": "inventory-service", "type": "http"},
    {"service": "payment-service", "type": "grpc"}
  ]
}

Step 4: Add the GitHub Action

Add the Buildpathio check step to your existing CI workflow:

.github/workflows/buildpath-check.yml

- name: Buildpathio dependency check
  uses: buildpathio/buildpath-action@v2
  with:
    token: ${{ secrets.BUILDPATH_TOKEN }}
    manifest: ./buildpath-manifest.json

Step 5: Open your first PR

Push a branch and open a pull request. Within 20–40 seconds, Buildpathio posts a check to your PR showing the full downstream impact of your changes:

BREAKING — a contract change that will break consumers
WARNING — a deprecation or interface drift that needs review
UNAFFECTED — downstream services that are safe

BREAKING blocks merge by default in the Pro and Team plans. You can override this with a justification comment (audited). On the Starter plan it's informational only.

Next steps

Full API reference — manifests, graph queries, impact analysis endpoints
GitHub App setup — OAuth install, PR annotations, and required checks
GitLab pipeline — cloud + self-hosted setup