> This page is for Itential Platform Cloud.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-test.itntl.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-test.itntl.com/_mcp/server.

# Build automation repositories

> Minimum requirements and process for configuring a custom pre-built automation repository in GitLab, including versioning, branch naming, and required file structure.

> **Info**
>
> The [Itential Open Source Pre-Builts repository](https://gitlab.com/itentialopensource/pre-built-automations) is no longer actively maintained. Those pre-builts have been certified up to Platform 2023.2, but can still be imported to Platform 6. We recommend transitioning to [Projects](/itential-platform/studio/projects/overview) for the best experience.

This guide defines the minimum requirements and process to have a functioning **Pre-built Automation** repository. Once configured properly, **Admin Essentials** is able to query the repository and incorporate and manage your custom pre-built automations.

Itential Platform supports the configuration of custom and multiple pre-built automation repositories. This means you can provide a configuration to fetch pre-built automations from your own custom repository, as opposed to previous releases where it was only possible to pull from Itential's official open-source library.

The following conventions must be followed for Admin Essentials to properly integrate with the custom pre-built automation repository.

## Structure of a pre-built automation repository

The pre-built automation repository must be in `GitLab`. Each pre-built automation is its own `GitLab` repository.

The branching strategy within each `GitLab` repository can be customized for development purposes; however, for a pre-built automation to properly appear in Admin Essentials, each must follow a specific branch naming convention considered as the `release` branches.

### Pre-built automation versioning requirements

Most Itential Platform releases follow a version convention like the one below:

`x.y.z-2023.1.m`

The "2023.1" equates to the major release of Itential Platform and the "m" is the maintenance release.

For a pre-built automation to be consumed by an Itential Platform environment with the above version, the pre-built automation must also have that same versioning structure in the `package.json` file. The version uses the traditional `major.minor.patch` Semantic Versioning, followed by a dash ("-") and the corresponding major release of Itential Platform (YYYY.Z), then each change to the prebuilt increments the maintenance number.

> **Info**
>
> One branch can only support one version of Itential Platform. For the version checking features to function properly, these rules must be followed on creation of the pre-built automation.

### Branch naming requirement for pre-built automations

The pre-built automation must also be tied to a specific release by creating a branch named with `release/YYYY.Z`. This versioning scheme is accomplished by having different Git branches to reflect different release versions.

For example, if you have a custom pre-built automation, the repository branches would be:

```bash
* master
* release/2021.1 -> consumable byItential Platform release/2021.1
* release/2020.2 -> consumable byItential Platform release/2020.2
* release/2020.1 -> consumable byItential Platform release/2020.1
```

## Structure of a pre-built automation

Each pre-built automation must include the following directories and files to be consumable by Itential Platform:

```bash
/bundles/
README.md
manifest.json
package.json
artifact.json
```

### bundles

The `bundles` directory consists of a directory map of all Itential Platform component files contained within the pre-built automation. An example directory structure for a pre-built automation that contains one of each supported component type (two transformations) would be:

```bash
/bundles
|--> /ac_-_agenda_job
    |--> automation-catalog-1.json
|--> /forms
    |--> form-1.json
|--> /golden_config
    |--> golden-config-1.json
|--> /json_forms
    |--> json-forms.json
|--> /mop_template
    |--> mop-template-1.json
|--> /mop_analytic_template
    |--> mop-analytic-template-1.json
|--> /service_catalog
    |--> service-catalog-1.json
|--> /template
    |--> template-1.json
|--> /transformation
    |--> transformation-1.json
    |--> transformation-2.json
|--> /workflow
    |--> workflow.json
```

The JSON files under each sub-directory contain the data for that component type. These files are the exports from an Itential Platform environment.

### README.md

Every pre-built automation is required to have a `README.md` file. This file describes the contents and use-cases of the pre-built automation and is displayed on the Admin Essentials Browse page as well as when browsing a pre-built automation's Details.

### manifest.json

The `manifest.json` file is a map of all components contained within the pre-built automation. It informs Itential Platform of the content along with the name, type, and location of each component in the bundle.

```json
{
  "bundleName": "Custom Pre-built Automation",
  "artifacts": [
    {
      "id": "Automation Catalog Name 1",
      "name": "Automation Catalog Name 1",
      "type": "ac-agenda-job",
      "location": "/bundles/ac_agenda_jobs/automation-catalog-1.json"
    },
    {
      "id": "Form Name 1",
      "name": "Form Name 1",
      "type": "forms",
      "location": "/bundles/forms/form-1.json"
    },
    {
      "id": "Golden Config Name 1",
      "name": "Golden Config Name 1",
      "type": "golden-config",
      "location": "/bundles/golden-config/golden-config-1.json"
    },
    {
      "id": "Json Form Name 1",
      "name": "Json Form Name 1",
      "type": "json-forms",
      "location": "/bundles/json_forms/json-forms.json"
    },
    {
      "id": "MOP Template 1",
      "name": "MOP Template 1",
      "type": "mop-template",
      "location": "/bundles/mop_template/mop-template-1.json"
    },
    {
      "id": "MOP Analytic Template 1",
      "name": "MOP Analytic Template 1",
      "type": "mop-analytic-template",
      "location": "/bundles/mop_analytic_template/mop-analytic-template-1.json"
    },
    {
      "id": "Service Catalog 1",
      "name": "Service Catalog 1",
      "type": "service-catalog",
      "location": "/bundles/service_catalog/service_catalog-1.json"
    },
    {
      "id": "Template 1",
      "name": "Template 1",
      "type": "template",
      "location": "/bundles/template/template-1.json"
    },
    {
      "id": "Transformation 1",
      "name": "Transformation 1",
      "type": "transformation",
      "location": "/bundles/transformation/transformation-1.json"
    },
    {
      "id": "Workflow Name",
      "name": "Workflow Name",
      "type": "workflow",
      "location": "/bundles/workflow/workflow.json"
    }
  ]
}
```

### package.json

The `package.json` file follows conventions set by `npm`.

```json
{
  "name": "Custom Pre-built Automation",
  "version": "1.0.0-2021.1.1",
  "description": "A description of the Pre-built Automation",
  "author": "John Doe",
  "license": "Apache-2.0",
  "repository": {
    "type": "gitlab",
    "hostname": "gitlab.com",
    "path": "/path/to/my/prebuilts-repo"
  },
  "IAPDependencies": {
    "@itential/app-automation_catalog": "2.5.4",
    "@itential/app-json_forms": "1.13.5",
    "@itential/app-workflow_engine": "6.7.10"
  }
}
```

### artifact.json

The `artifact.json` file is the most important aspect of the pre-built automation. It's a combination of all the files mentioned above, containing all the information needed to consume a pre-built automation into an Itential Platform environment.

The `metadata` property contains the `package.json`; `manifest` contains the `manifest.json`; and `bundles` is the concatenation of each of the files under the `/bundles` directory.

> **Info**
>
> For ease of reading, the actual content for the bundles directory is represented by ellipses.

```json
{
  "metadata": {
    "name": "Custom Pre-built Automation",
    "version": "1.0.0-2021.1.1",
    "description": "A description of the Pre-built Automation",
    "author": "John Doe",
    "license": "Apache-2.0",
    "repository": {
      "type": "gitlab",
      "hostname": "gitlab.com",
      "path": "/path/to/my/prebuilts-repo"
    },
    "IAPDependencies": {
      "@itential/app-automation_catalog": "2.5.4",
      "@itential/app-json_forms": "1.13.5",
      "@itential/app-workflow_engine": "6.7.10"
    }
  },
  "manifest": {
    "bundleName": "Custom Pre-built Automation",
    "artifacts": [
      {
        "id": "Automation Catalog Name 1",
        "name": "Automation Catalog Name 1",
        "type": "ac-agenda-job",
        "location": "/bundles/ac_agenda_jobs/automation-catalog-1.json"
      },
      {
        "id": "Workflow Name",
        "name": "Workflow Name",
        "type": "workflow",
        "location": "/bundles/workflow/workflow.json"
      }
    ]
  },
  "bundles": [
    { "type": "ac-agenda-job", "data": { ... } },
    { "type": "forms", "data": { ... } },
    { "type": "golden-config", "data": { ... } },
    { "type": "json-form", "data": { ... } },
    { "type": "mop-template", "data": { ... } },
    { "type": "mop-analytic-template", "data": { ... } },
    { "type": "service-catalog", "data": { ... } },
    { "type": "template", "data": { ... } },
    { "type": "transformation", "data": { ... } },
    { "type": "workflow", "data": { ... } }
  ],
  "readme": "Markdown text goes here"
}
```