Sync DATAMIMIC Project with a Git Branch

Warning

The current page still doesn't have a translation for this language.

But you can help translating it: Contributing.

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

Git synchronization is also available through the DATAMIMIC UI via a git-pull button in the editor, which syncs the repository's default branch. This API additionally allows specifying an arbitrary branch_name.

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/v2/projects/{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/v2/projects/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 and the durable task ID

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

Handling Long-Running Updates (503 + Polling)

For a non-trivial repository, the clone/checkout may not finish within the request's ~5 second window. In that case the endpoint returns 503 Service Unavailable instead of 201 Created, with code: "PROJECT_GIT_UPDATE_PENDING" and a task_id in the response. This is expected behavior, not an error — poll the following endpoint with that task_id until the update completes:

curl -X 'GET' \
  'https://your-datamimic-instance/api/v2/projects/{project-id}/git/tasks/{task-id}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-project-access-token}'

Keep polling until the task's status is no longer running.

API Response Examples

Successful Response

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

{
  "message": "Project successfully synced with Git branch 'development'",
  "task_id": "9ddbd794-ace8-4b61-8c31-55232c6dc482"
}

Error Responses

Authentication Failed

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

{
  "detail": "Authentication failed"
}

Project Not Found

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

{
  "detail": "Project not found"
}

Project Not Configured for Git

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "detail": "Project is not configured for Git pulls. Configure remote_url and git_repo_type first.",
  "code": "PROJECT_GIT_UPDATE_INVALID_REQUEST"
}

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/v2"
export BRANCH_NAME="development"

# Sync with Git branch
curl -X 'PUT' \
  "${API_BASE}/projects/${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
3. 400 Bad Request: Verify that the project is configured as a Git project (remote_url and git_repo_type set)
4. 422 Unprocessable Entity: Ensure the branch name is valid and exists in your Git repository
5. 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