Skip to main content

Integration Guide

CLOUD

Integrate msh Cloud Platform with your CI/CD pipeline and workflows.

CLI Integration​

Upload Metadata Script​

Create a script to upload metadata:

#!/bin/bash
# upload-metadata.sh

PROJECT_ID=${MSH_PROJECT_ID:-1}
API_TOKEN=${MSH_API_TOKEN}

if [ -z "$API_TOKEN" ]; then
  echo "Error: MSH_API_TOKEN not set"
  exit 1
fi

# Generate context pack
msh ai context --json > context.json

# Upload to cloud
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"context_pack\": $(cat context.json), \"source\": \"cli\"}" \
  https://api.msh.io/api/msh/metadata/projects/$PROJECT_ID/upload

echo "Metadata uploaded successfully"

Usage:

export MSH_API_TOKEN="your-token"
export MSH_PROJECT_ID=1
./upload-metadata.sh

CI/CD Integration​

GitHub Actions​

# .github/workflows/msh-sync.yml
name: Sync msh Metadata

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  sync-metadata:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install msh
        run: pip install msh-cli
      
      - name: Generate context pack
        run: msh ai context --json > context.json
      
      - name: Upload to cloud
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.MSH_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d "{\"context_pack\": $(cat context.json), \"source\": \"webhook\"}" \
            https://api.msh.io/api/msh/metadata/projects/${{ secrets.MSH_PROJECT_ID }}/upload

GitLab CI​

# .gitlab-ci.yml
sync-metadata:
  stage: deploy
  image: python:3.11
  before_script:
    - pip install msh-cli
  script:
    - msh ai context --json > context.json
    - |
      curl -X POST \
        -H "Authorization: Bearer $MSH_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{\"context_pack\": $(cat context.json), \"source\": \"webhook\"}" \
        https://api.msh.io/api/msh/metadata/projects/$MSH_PROJECT_ID/upload
  only:
    - main

Pre-Deploy Safety Checks​

Add safety checks to your deployment pipeline:

# .github/workflows/deploy.yml
name: Deploy with Safety Checks

on:
  pull_request:
    branches: [main]

jobs:
  safety-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run pre-deploy safety check
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.MSH_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "asset_id": 5,
              "new_version": "${{ github.sha }}",
              "diff": {...}
            }' \
            https://api.msh.io/api/msh/ai/pre-deploy-check

Webhook Integration​

Set up webhooks to automatically sync metadata:

# Configure webhook URL in Cloud Platform
# Webhook will be called on metadata updates

API Clients​

Python Client​

import requests

class MSHCloudClient:
    def __init__(self, api_token, project_id):
        self.api_token = api_token
        self.project_id = project_id
        self.base_url = "https://api.msh.io/api/msh"
    
    def upload_metadata(self, context_pack):
        response = requests.post(
            f"{self.base_url}/metadata/projects/{self.project_id}/upload",
            headers={
                "Authorization": f"Bearer {self.api_token}",
                "Content-Type": "application/json"
            },
            json={"context_pack": context_pack, "source": "api"}
        )
        return response.json()
    
    def semantic_search(self, query, entity_types=None):
        response = requests.post(
            f"{self.base_url}/ai/semantic-search",
            headers={
                "Authorization": f"Bearer {self.api_token}",
                "Content-Type": "application/json"
            },
            json={
                "query": query,
                "project_id": self.project_id,
                "entity_types": entity_types or ["asset", "term", "metric"]
            }
        )
        return response.json()

JavaScript Client​

class MSHCloudClient {
  constructor(apiToken, projectId) {
    this.apiToken = apiToken;
    this.projectId = projectId;
    this.baseUrl = 'https://api.msh.io/api/msh';
  }
  
  async uploadMetadata(contextPack) {
    const response = await fetch(
      `${this.baseUrl}/metadata/projects/${this.projectId}/upload`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          context_pack: contextPack,
          source: 'api'
        })
      }
    );
    return response.json();
  }
  
  async semanticSearch(query, entityTypes = ['asset', 'term', 'metric']) {
    const response = await fetch(
      `${this.baseUrl}/ai/semantic-search`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          query,
          project_id: this.projectId,
          entity_types: entityTypes
        })
      }
    );
    return response.json();
  }
}

Best Practices​

  1. Automate Syncs: Set up CI/CD to automatically sync metadata
  2. Error Handling: Handle API errors gracefully
  3. Rate Limiting: Respect rate limits and implement retries
  4. Security: Never commit API tokens to version control
  5. Monitoring: Monitor sync status and failures