Sync DATAMIMIC Project with a Git Branch

This guide explains how to synchronize your DATAMIMIC project with a specific Git branch using API calls. This feature allows you to keep your project in sync with your Git repository, pulling the latest changes from any branch and overriding your DATAMIMIC project content.

Warning

This operation will overwrite all local changes in your DATAMIMIC project with the content from the specified Git branch. Make sure to save any important work before proceeding.

Note

Currently, Git branch synchronization is only available via API and cannot be performed through the DATAMIMIC UI.

Prerequisites

• A DATAMIMIC project that is properly configured as a Git Project
• A Project Access Token for API authentication
• A http client tool installed on your system. We will use curl in this guide.
• Access to the Git repository and the specific branch you want to sync with

Step-by-Step Guide

Step 1: Create a DATAMIMIC Git Project

If you haven't already created a Git-connected DATAMIMIC project, follow these steps:

1. Navigate to the Project View
2. Click the (+) button to create a new project
3. Select Git Project from the Project Wizard Options
4. Select your Git provider and provide your Git repository URL and authentication details
5. Complete the project creation process

For detailed instructions, refer to the Git Project creation documentation.

Step 2: Generate a Project Access Token

To interact with your project via API, you need a project access token:

1. Navigate to your project
2. Go to Settings → Tokens
3. Add a new project access token
4. Copy and securely store both the Project ID and the Project Access Token

If you are not familiar with project access token, we recommend you to read the Project Access Token documentation.

Step 3: Sync with Git Branch

Use the following API endpoint to synchronize your DATAMIMIC project with a specific Git branch:

curl -X 'PUT' \
  'https://your-datamimic-instance/api/v1/{project-id}/git?branch_name={branch-name}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-project-access-token}'

Parameters

• {project-id}: Your DATAMIMIC project identifier
• {branch-name}: The Git branch name you want to sync with (e.g., development, main, feature/new-feature)
• {your-project-access-token}: Your project access token

Example

curl -X 'PUT' \
  'https://datamimic.example.com/api/v1/abc123-def456-ghi789/git?branch_name=development' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer dm_pat_1234567890abcdef'

Step 4: Verify Success

Upon successful execution, the API will return:

• HTTP Status Code: 201 Created
• Response: A success message confirming the operation

The server will:

1. Clone your Git repository
2. Checkout the specified branch
3. Replace all files in your DATAMIMIC project with the content from the Git branch
4. Create a snapshot of the updated project

API Response Examples

Successful Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "message": "Project successfully synced with Git branch 'development'"
}

Error Responses

Authentication Failed

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "detail": "Authentication failed"
}

Project Not Found or Not a Git Project

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "detail": "Project not found or Git repository not configured"
}

Invalid Branch Name

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "detail": "Invalid branch name or branch does not exist"
}

Advanced Usage

Environment Variables Setup

For easier management, you can set up environment variables:

# Set your variables
export PROJECT_ID="your-project-id"
export ACCESS_TOKEN="your-project-access-token"
export API_BASE="https://your-datamimic-instance/api/v1"
export BRANCH_NAME="development"

# Sync with Git branch
curl -X 'PUT' \
  "${API_BASE}/${PROJECT_ID}/git?branch_name=${BRANCH_NAME}" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Best Practices

1. Backup Important Work: Always ensure your local changes are committed to Git or backed up before syncing
2. Test with Non-Production Branches: Test the sync process with development or feature branches before using it with production branches
3. Verify Branch Existence: Ensure the target branch exists in your Git repository before attempting to sync
4. Use Descriptive Branch Names: Use clear, descriptive branch names that follow your team's naming conventions
5. Monitor API Responses: Always check the HTTP status code and response message to ensure successful operations

Troubleshooting

Common Issues

1. 401 Unauthorized: Check that your project access token is valid and has the necessary permissions
2. 404 Not Found: Verify that the project ID is correct and the project is configured as a Git project
3. 422 Unprocessable Entity: Ensure the branch name is valid and exists in your Git repository
4. 500 Internal Server Error: Check your Git repository access credentials and network connectivity

Getting Help

• Review the DATAMIMIC External API Reference for complete API documentation
• Check your DATAMIMIC instance's external_api_docs for interactive API documentation
• Refer to the Project Access Token guide for authentication troubleshooting