1. Overview

This guide describes how to set up an automated pipeline that exports SysML v2 textual notation from CATIA Magic Teamwork Cloud (TWC) and commits it to a GitLab repository. The automation is triggered by TWC webhooks when a user creates a tagged commit, ensuring that every significant model revision is captured in version control as human-readable SysML v2 text.

Figure: GitLab — Repository showing exported sysml file, python script which used REST API to get sysml file, and pipeline configuration file automating process.

Figure: GitLab — Repository showing updated .sysml file and commit history

Demo:

https://youtu.be/guDRYXwZomU

Note! SysML v2 Rest API to export. sysml file will be available with v2026x R1 release 2026 July. This is early demonstration. You can use SysML v2 current REST API with other use cases like running simulation or exporting requirements.

2. Architecture

The solution consists of four integrated components working together in a fully automated workflow:

3. Automation Flow

1. A systems engineer commits changes in CATIA Magic and applies a "SysML" tag to the commit in Teamwork Cloud.

2. The TWC webhook detects the tagged commit and fires an HTTP POST request to the GitLab pipeline trigger endpoint.

3. GitLab receives the trigger and starts the CI/CD pipeline on the self-hosted Windows runner.

4. The Python script (sync_sysml.py) fetches the latest commit from the TWC SysML v2 API.

5. The script exports the SysML v2 textual notation and pushes it as a .sysml file to the GitLab repository.

6. The .sysml file is also saved as a downloadable CI/CD artifact with 30-day retention.

4. Prerequisites

Before starting, ensure the following are available:

•  A Teamwork Cloud server with SysML v2 API enabled (port 8443)

•  A SysML v2 project hosted on TWC

•  A GitLab instance (self-hosted or cloud) accessible from the TWC network

•  A Windows machine on the same network as TWC (for the GitLab Runner)

•  Python 3.10+ installed on the runner machine

•  Administrative access to both TWC and GitLab

5. Step-by-Step Setup

STEP 1  Create the GitLab Project

Create a new project in GitLab to store the exported SysML v2 files. This repository will serve as the version-controlled archive of your model.

1.1 Navigate to your GitLab instance and click New Project.

1.2 Choose "Create blank project" and fill in:

1.3 Click Create project. Note the Project ID shown on the project page (e.g., 9128).

Figure: GitLab — New Project creation page

STEP 2  Install & Register the GitLab Runner

A self-hosted GitLab Runner is required because the TWC server is on an internal corporate network that cloud-based runners cannot reach. The runner must be installed on a Windows machine with network access to both TWC and GitLab.

2.1 Download the GitLab Runner binary for Windows from the GitLab documentation site.

2.2 Create a directory for the runner:

mkdir C:\\GitLab-Runner

2.3 Place the downloaded executable as gitlab-runner.exe in that directory.

2.4 In GitLab, go to your project: Settings → CI/CD → Runners → Expand. Click "New project runner" and note the registration token.

Figure: GitLab — Runner registration settings page

2.5 Open PowerShell as Administrator and register the runner:

cd C:\\GitLab-Runner

.\\gitlab-runner.exe register

# When prompted, enter:

#  GitLab URL:      https:// name>

#  Registration token:

#  Description:     

#  Tags:            shell, windows

#   Executor:        shell

2.6 Install and start the runner as a Windows service:

.\\gitlab-runner.exe install

.\\gitlab-runner.exe start

.\\gitlab-runner.exe status   # Should show: running

STEP 3  Configure CI/CD Variables

The pipeline script requires authentication tokens to access both TWC and GitLab APIs. These are stored securely as masked CI/CD variables.

3.1 Go to your GitLab project: Settings → CI/CD → Variables → Expand.

3.2 Add the following variables:

Figure: GitLab — CI/CD Variables configuration with Protected unchecked

3.3 To generate a TWC token, use the Teamwork Cloud administration panel or create a personal access token via the TWC REST API.

3.4 To generate a GitLab token, go to your GitLab profile: Edit Profile → Access Tokens. Create a token with api and write_repository scopes.

STEP 4  Add Pipeline Files to the Repository

Two files are needed in the GitLab repository: the CI/CD configuration file and the Python sync script.

6. .gitlab-ci.yml

Create this file in the root of the repository. It defines the pipeline stages, triggers, and script execution.

stages:

 - sync

variables:

 GIT_STRATEGY: clone

 GIT_DEPTH: 0

sync_sysml_from_twc:

 stage: sync

 rules:

   - if: \\\$CI_PIPELINE_SOURCE == "schedule"

   - if: \\\$CI_PIPELINE_SOURCE == "web"

      when: manual

   - if: \\\$CI_PIPELINE_SOURCE == "trigger"

 script:

   - pip install requests --quiet

   - python scripts/sync_sysml.py

 artifacts:

   paths:

      - "*.sysml"

   when: on_success

    expire_in: 30 days

7. scripts/sync_sysml.py

Create a scripts/ directory in the repository and add the sync script. This Python script performs the actual work of fetching from TWC and pushing to GitLab.

The script performs these operations:

1. Connects to the TWC SysML v2 API using multi-auth fallback (no auth, Token, Bearer)

2. Fetches all commits and selects the latest one

3. Checks the last_synced_commit.txt tracking file to avoid duplicate syncs

4. Retrieves the root namespace and exports SysML v2 textual notation

5. Falls back to element-based reconstruction if direct export fails

6. Commits and pushes the .sysml file and tracking file to GitLab using native git

Key configuration values (hardcoded defaults, overridable via CI/CD variables):

The full script file (sync_sysml.py) is provided as a separate attachment to this document. Place it at scripts/sync_sysml.py in the repository.

8. Repository Structure

After setup, the repository should have this structure:

sysml-v2-twc/

├── .gitlab-ci.yml                 # Pipeline configuration

├── scripts/

│  └── sync_sysml.py              # TWC sync script

├── Stock Market Ticker.sysml      # Auto-generated SysML export

├── last_synced_commit.txt         # Tracks last synced TWC commit

└── README.md

STEP 5  Create a Pipeline Trigger Token

A pipeline trigger token allows external systems (like TWC) to start pipelines via an HTTP POST request.

5.1 In GitLab, go to: Settings → CI/CD → Pipeline trigger tokens → Expand.

5.2 Click "Add new token" and provide a description (e.g., "TWC Webhook Trigger").

5.3 Copy the generated token. It will look like: glptt-xxxxxxxxxxxxxxxxxxxx

Figure: GitLab — Pipeline trigger token creation

5.4 Test the trigger from PowerShell:

# Bypass SSL certificate validation for self-signed certs

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {\\\$true}

Invoke-RestMethod -Method POST `

 -Uri "https://api/v4/projects/9128/trigger/pipeline" `

  -Body @{token="glptt-xxxxxxxxxxxxxxxxxxxx"; ref="main"}

If successful, the response will contain a pipeline ID and status "created".

STEP 6  Configure the TWC Webhook

The final piece connects TWC to GitLab by configuring a webhook that fires when a tagged commit is created.

6.1 Open the Teamwork Cloud administration panel (typically at https://your-twc-server:8443/admin).

6.2 Navigate to: Webhooks → Add webhook.

6.3 Configure the webhook with the following settings:

Figure: Teamwork Cloud — Webhook configuration panel

6.4 The webhook URL includes the pipeline trigger token and branch reference as query parameters. When TWC fires the webhook, it sends a POST to this URL, which GitLab interprets as a pipeline trigger.

STEP 7  Test the End-to-End Flow

With all components configured, test the complete automation:

7.1 Open your SysML v2 project in CATIA Magic.

7.2 Make a change to the model (e.g., update a requirement text).

7.3 Commit the change to Teamwork Cloud and apply the "Major" tag.

7.4 Check GitLab → Build → Pipelines. A new pipeline should appear within seconds.

Figure: GitLab — Pipeline running after TWC webhook trigger

7.5 Once the pipeline completes, verify:

  •  The .sysml file in the repository is updated with the latest model content.

  •  The last_synced_commit.txt contains the TWC commit ID.

  •  A downloadable .sysml artifact is available on the job page.

Figure: GitLab — Repository showing updated .sysml file and commit history

9. Troubleshooting

10. Quick Reference

11. Files Provided

The following files accompany this document and should be placed in the GitLab repository:

For questions or issues, review the pipeline job logs in GitLab (Build → Jobs) for detailed diagnostic output from the sync script.