Skip to main content

Git Sync (Mock-as-Code)

Git Sync lets you version-control your mock API definitions in a git repository. You define routes, responses, and configurations as YAML files, commit them to source control, and sync them to SureStage Sandboxes automatically.

Why Use Git Sync​

  • Version control - Track changes to mock definitions over time
  • Code review - Review mock changes in pull requests alongside application code
  • Reusability - Share mock configurations across teams via git
  • CI/CD integration - Automate mock deployment in your pipeline
  • Disaster recovery - Your mocks are backed up in source control

How It Works​

  1. Connect a git repository to your Sandbox
  2. SureStage reads YAML files from the repo and creates routes, responses, and state
  3. When you push changes to the connected branch, SureStage syncs automatically
  4. You can also trigger manual syncs via API or UI

Connecting a Repository​

Prerequisites​

  • A git repository (GitHub, GitLab, Bitbucket, or self-hosted)
  • Repository access token with read permissions
  • YAML mock definitions in the repository

Create a Connection​

curl -X POST https://api.surestage.com/v1/git/connections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryUrl": "https://github.com/yourorg/mocks.git",
    "branch": "main",
    "accessToken": "ghp_yourtoken",
    "sandboxId": "sandbox_abc123",
    "syncPath": "/mocks"
  }'

Response 201 Created

{
  "id": "conn_xyz789",
  "repositoryUrl": "https://github.com/yourorg/mocks.git",
  "branch": "main",
  "sandboxId": "sandbox_abc123",
  "syncPath": "/mocks",
  "status": "connected",
  "lastSyncAt": null,
  "createdAt": "2026-03-21T10:30:00Z"
}

Parameters​

FieldTypeRequiredDescription
repositoryUrlstringYesHTTPS git clone URL
branchstringYesBranch to sync from
accessTokenstringYesGit provider access token (stored encrypted)
sandboxIdstringYesTarget Sandbox ID
syncPathstringNoDirectory in repo containing mocks (default: root)

YAML File Format​

SureStage uses YamlSerializerService to parse mock definitions. Files must follow this structure:

Route Definition​

# /mocks/users/get-user.yaml
method: GET
path: /users/:id
response:
  status: 200
  headers:
    Content-Type: application/json
  body:
    id: "{{params.id}}"
    name: "John Doe"
    email: "john@example.com"
validation:
  params:
    id:
      type: string
      required: true

Environment Definition​

# /mocks/_environments/users.yaml
name: Users API
description: User management endpoints
routes:
  - method: GET
    path: /users
    response:
      status: 200
      body:
        - id: "1"
          name: "Alice"
        - id: "2"
          name: "Bob"
  - method: POST
    path: /users
    response:
      status: 201
      body:
        id: "{{$randomUUID}}"
        name: "{{body.name}}"

Stateful Scenario​

# /mocks/checkout/checkout-flow.yaml
scenario: CheckoutFlow
initialState:
  cart: []
  total: 0
routes:
  - method: POST
    path: /cart/add
    mutations:
      - type: append
        target: state.cart
        value: "{{body.item}}"
    response:
      status: 200
      body:
        cart: "{{state.cart}}"
  - method: POST
    path: /cart/checkout
    response:
      status: 200
      body:
        orderId: "{{$randomUUID}}"
        total: "{{state.total}}"

Triggering a Sync​

Manual Sync via API​

curl -X POST https://api.surestage.com/v1/git/connections/conn_xyz789/sync \
  -H "Authorization: Bearer $TOKEN"

Response 202 Accepted

{
  "syncId": "sync_def456",
  "status": "in_progress",
  "startedAt": "2026-03-21T11:00:00Z"
}

Webhook-Triggered Sync​

Configure a webhook in your git provider to trigger syncs on push:

Webhook URL

https://api.surestage.com/v1/git/connections/conn_xyz789/webhook

Headers

X-Webhook-Secret: your_webhook_secret

The connection will sync automatically when you push to the connected branch.

Managing Connections​

List Connections​

curl https://api.surestage.com/v1/git/connections?sandboxId=sandbox_abc123 \
  -H "Authorization: Bearer $TOKEN"

Update Connection​

curl -X PATCH https://api.surestage.com/v1/git/connections/conn_xyz789 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "develop",
    "syncPath": "/api-mocks"
  }'

Delete Connection​

curl -X DELETE https://api.surestage.com/v1/git/connections/conn_xyz789 \
  -H "Authorization: Bearer $TOKEN"

Deleting a connection does not delete the Sandbox or its routes. It only removes the git sync configuration.

Security​

  • Access tokens are encrypted at rest using AES-256
  • All git operations are protected by JwtAuthGuard and TenantGuard to prevent cross-Tenant access
  • Webhook secrets are validated on every incoming request
  • SureStage never writes back to your repository (read-only access)

Common Issues​

Problem: Sync fails with "Authentication failed"

Solution: Verify your access token has not expired. Generate a new token with read permissions and update the connection.

Problem: Routes not appearing after sync

Solution: Check the syncPath matches the directory containing your YAML files. Verify YAML syntax is valid using a linter.

Problem: Webhook not triggering syncs

Solution: Verify the webhook URL is correct and the X-Webhook-Secret header matches the secret in your connection settings.