Skip to content

GitOps

It is highly recommended to set up a git repository to manage the Service Schemas. A Git repository allows Service Owners to track changes, request reviews, and obtain approval from team members before applying modifications. Therefore, they can have more supervision on their Schemas. NetOrca provides CI/CD scripts for validating and submitting the Service Schema. So, as soon as Service Owners push new commits or merge their Merge Requests, their Services will be updated immediately on NetOrca.

Set Up Repository

Create a directory where you want to keep all files regarding your Service Schemas, and then initialize a git repository inside the directory.

mkdir netorca_services
cd netorca_services
git init

Service Owners can also use NetOrca's Template repository which includes CI/CD scripts for Schema validation and submission. In order to clone and use the template:

git clone https://gitlab.com/netorca_public/serviceowner_template.git
cd serviceowner_template

Api Key Authentication

The CI/CD script requires an environment variable named NETORCA_API_KEY for authentication. In order to create a team and an Api Key, please follow the instruction on API KEY management page.

Repository Structure

The following is an overview of the Service Owner's git repository structure:

git_root_directory/
  ├── .netorca/
  │   ├── config.yaml
  │   ├── <service_1_name>.json
  │   ├── <service_1_name>.md
  │   ├── <service_2_name>.yaml
  │   └── <service_2_name>.md
  └── .gitlab-ci.yml

An example repository with GitLab CI and CI/CD tooling can be found at https://gitlab.com/netorca_public/serviceowner_template.

Both styles can be mixed in the same repository. Services using NetOrca Pack can use the per-service subdirectory structure to keep pack scripts and context files alongside the schema:

git_root_directory/
  ├── .netorca/
  │   ├── config.json
  │   ├── <service_1_name>/
  │   │   ├── service.json
  │   │   ├── service.md
  │   │   ├── pack/
  │   │   │   ├── config.txt
  │   │   │   ├── config.json       (response schema for non-UE services)
  │   │   │   ├── verify.txt
  │   │   │   ├── verify.json
  │   │   │   ├── execute.txt
  │   │   │   └── execute.json
  │   │   └── context/
  │   │       ├── ip_names.txt          (IP naming conventions, reserved ranges, etc.)
  │   │       ├── devices.json          (device inventory or configuration reference)
  │   │       ├── api_docs.md           (API documentation for the service backend)
  │   │       ├── vlans.txt             (VLAN IDs and descriptions)
  │   │       ├── firewall_rules.json   (firewall policy reference)
  │   │       └── ...                   (any other reference material used by the pack scripts)
  │   └── <service_2_name>/
  │       └── ...
  └── .gitlab-ci.yml

config.json

This file contains the NetOrca base url. Here is an example of a config.json file:

{
  "netorca_global": {
    "base_url": "https://api.netorca.io/v1"
  }
}
In this file, netorca_global and base_url are the required keys.

<service_name>.json

Service Schema definition is basically a JSON Schema. You can find all detail for defiling the Schema in Service Definition. The final Service Schema JSON must be put in <service_name\>.json file. Here is an example of a JSON file for VM Service:

File Name: VM.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/service.schema.json",
  "title": "VM",
  "description": "Schema of a Virtual Machine",
  "type": "object",
  "metadata": {},
  "properties": {
    "name": {
      "type": "string",
      "description": "The unique identifier for a service item",
      "examples": ["CoreVM1"]
    },
    "cpu": {
      "type": "integer",
      "examples": [4, 8]
    }, 
    "memory": {
      "type": "integer",
      "examples": [4, 8, 16]
    }
  },
  "required": ["name", "cpu", "memory"]
}

<service_name>.md

As it is mentioned in README Markdown file for Service, Service Owners have the option to include a markdown file with their services to provide additional details. These markdown files can also be stored in the Git repository. NetOrca's CI/CD script identifies each service's markdown file by matching the service definition file name with the corresponding markdown file.

For the example service above the markdown file could be:

File Name: VM.md

# Virtual Machine Service

This a README file to explain more the VM service...

.gitlab-ci.yml

NetOrca provides a CI/CD script specifically for Service Validation and Submission. When Service Owners include this script in their repository, any push to the default branch (e.g., main or master) will trigger an automatic submission of the Service Schema definition to NetOrca. For other branches, the Schema will be sent to NetOrca for validation.

Below is the CI/CD script to be used in a GitLab repository:

stages:
  - validate
  - submit

image: python:3.10-buster
before_script:
  - pip install -q --upgrade pip
  - pip install -q netorca-sdk

validate:
  stage: validate
  variables:
    NETORCA_VALIDATE_ONLY: "True"
  script:
    - wget -q 'https://netautomate.gitlab.io/netorca_tools/cicd/latest/serviceowner_submission.py'
    - python serviceowner_submission.py
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

submit:
  stage: submit
  variables:
    NETORCA_VALIDATE_ONLY: "False"
  script:
    - wget -q 'https://netautomate.gitlab.io/netorca_tools/cicd/latest/serviceowner_submission.py'
    - python serviceowner_submission.py
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

include:
  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'

NetOrca Pack CI/CD

For services using NetOrca Pack, the CI/CD pipeline does more than just submit the Service Schema — it also keeps all Pack-related configuration in sync between your repository and your NetOrca instance.

When using the per-service subdirectory structure, each service can have a pack/ directory containing prompts and response schemas, and a context/ directory containing reference material for the AI Processors:

.netorca/
└── <service_name>/
    ├── service.json          # Service Schema
    ├── service.md            # Service README
    ├── pack/
    │   ├── config.txt        # Prompt for the CONFIG AI Processor
    │   ├── config.json       # Response schema for the CONFIG AI Processor
    │   ├── verify.txt        # Prompt for the VERIFY AI Processor
    │   ├── verify.json       # Response schema for the VERIFY AI Processor
    │   ├── execute.txt       # Prompt for the EXECUTION AI Processor
    │   └── execute.json      # Response schema for the EXECUTION AI Processor
    └── context/
        ├── devices.json
        ├── vlans.txt
        └── ...               # Any reference material used by the AI Processors

What the Pack CI/CD does

On every pipeline run, the CI/CD script reconciles the repository with your NetOrca instance for each service:

AI Processors

For each stage (config, verify, execute), if a corresponding .txt prompt file exists in the pack/ directory, the CI/CD script will:

  • Create the AI Processor in NetOrca if it does not already exist for that service and stage.
  • Update the prompt and response schema on the existing AI Processor if they have changed.

If a prompt file is removed from the repository, the corresponding AI Processor is deleted from NetOrca on the next pipeline run. This means your repository is the single source of truth — what is in your repo is what exists in NetOrca.

Context Documents

Files in the context/ directory are uploaded to NetOrca as Documents linked to the service. These documents provide extra context to all AI Processors for that service during LLM calls — for example, VLAN inventories, device lists, API documentation, or naming convention guides.

The CI/CD script syncs the context directory on every run:

  • New files are uploaded as new Documents.
  • Changed files replace the existing Document content.
  • Deleted files remove the corresponding Document from NetOrca.

Branch behaviour

The Pack CI/CD follows the same branch rules as Schema submission:

Branch Schema AI Processors & Context
Non-default branch (e.g. MR/PR) Validated only, not submitted Dry-run — changes are validated but not applied
Default branch (e.g. main) Submitted to NetOrca Applied — AI Processors and Documents are created/updated/deleted

This means you can safely develop and review Pack configuration changes in a Merge Request without affecting the live NetOrca instance until the branch is merged.