Skip to content

feat(gitlab): rebuild Studio Project on the Integration Model, drop the adapter #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michaelelrom merged 2 commits into from
Aug 12, 2026
Merged

feat(gitlab): rebuild Studio Project on the Integration Model, drop the adapter #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ce6d194
feat(gitlab): rebuild Studio Project on the Integration Model, drop t…
mikeelrom Aug 12, 2026
1af267b
docs(gitlab): update testing status now that List Groups is confirmed…
mikeelrom Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 71 additions & 39 deletions GitLab/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,47 +1,39 @@
GitLab is a web-based DevOps platform for Git version control, code review, issue tracking, and CI/CD pipelines.

This project provides two complementary ways to automate against GitLab:

- **Studio Project workflows** built on the **GitLab Adapter** — project, branch, merge request, and file/commit lifecycle workflows.
- **OpenAPI specs** for building new automation directly against GitLab's REST API via an Integration Model. The `-latest` spec is a curated subset covering common CRUD for repository and CI/CD automation — see **OpenAPIs** below.
This project provides OpenAPI specs for automating against GitLab's REST API via an Integration Model, plus a Studio Project of ready-to-import CRUD workflows built on that model.

## Table of Contents

- [Contents](#contents)
- [Requirements](#requirements)
- [Integration Configuration](#integration-configuration)
- [Adapter (Studio Project workflows)](#adapter-studio-project-workflows)
- [Integration Model (OpenAPI-based automation)](#integration-model-openapi-based-automation)
- [Studio Projects](#studio-projects)
- [GitLab Project](#gitlab-project)
- [OpenAPIs](#openapis)
- [`gitlab_rest_api-latest.json`](#gitlab_rest_api-latestjson)
- [`gitlab_rest_api-v4.json`](#gitlab_rest_api-v4json)
- [Studio Projects](#studio-projects)
- [GitLab Project](#gitlab-project)
- [Folder Structure](#folder-structure)
- [Dependencies](#dependencies)

## Contents

| Asset | Description |
|---|---|
| [OpenAPIs/](./OpenAPIs/) | GitLab REST API OpenAPI specs — curated `-latest` plus the full dated spec |
| [Studio Projects/](./Studio%20Projects/) | Itential Platform project containing the project/branch/merge-request/file workflows |
| [Studio Projects/](./Studio%20Projects/) | Itential Platform project containing all 133 workflows in 21 folders |

## Requirements

| Requirement | Version |
|---|---|
| Itential Platform | 6.x |
| GitLab Adapter | Required for the Studio Project workflows below |
| GitLab Integration Model | Required only if building new automation directly against the OpenAPI specs |
| `GitLab REST API:latest` Integration Model | Required to build automation against the OpenAPI specs, and to run the Studio Project below |

## Integration Configuration
> **Note:** This project does not require Itential Gateway. All API calls are made directly from Itential Platform to GitLab's REST API.

### Adapter (Studio Project workflows)

Install the [GitLab Adapter](https://gitlab.com/itentialopensource/adapters/adapter-gitlab) and configure an instance in **Admin > Adapters**, then update the `adapterId` value (`$var.job.adapterId`) in each workflow task to match your instance name before importing.

### Integration Model (OpenAPI-based automation)
## Integration Configuration

To build automation directly against the REST API instead, import `OpenAPIs/gitlab_rest_api-latest.json` as an Integration Model in **Admin > Integrations**, then create an integration pointing at your GitLab instance (or `gitlab.com` for GitLab SaaS).
Import `gitlab_rest_api-latest.json` as an Integration Model in **Admin > Integrations**, then create an integration pointing at your GitLab instance (or `gitlab.com` for GitLab SaaS).

Authentication is an API key in the `PRIVATE-TOKEN` header:

Expand All @@ -51,27 +43,22 @@ PRIVATE-TOKEN: <your-personal-access-token>

Generate a Personal Access Token (or group/project access token) at GitLab → User Settings → Access Tokens.

---

## Studio Projects

### GitLab Project

| Folder | Workflows | Scope |
|---|---|---|
| Create Project | Create Project | Create a new project in a namespace |
| Create Templated Project | Create Templated Project | Create a project from an existing template project |
| Push Commit to Branch | Push Commit to Branch | Read an existing file and push an updated commit to a branch |
| Get Diff for Merge | Get Diff for Merge | Retrieve merge request diff versions |
| (root) | Get Branch, Get File, Create Branch, Create Merge Request, Update Project Variables | Read a branch or file; create a branch or merge request; update a project CI/CD variable |

#### Dependencies

| Dependency | Notes |
|---|---|
| [GitLab Adapter](https://gitlab.com/itentialopensource/adapters/adapter-gitlab) | Required for the Studio Project workflows. Update the `adapterId` in each workflow task to match your instance name. |

---
The instance's `authentication`/`server` properties should look like this once configured:

```json
{
"authentication": {
"access_token_header": {
"value": "<your-personal-access-token>"
}
},
"server": {
"protocol": "https",
"host": "gitlab.com",
"base_path": ""
}
}
```

## OpenAPIs

Expand Down Expand Up @@ -111,3 +98,48 @@ Resources included, by category:
### `gitlab_rest_api-v4.json`

Full, unmodified vendor spec for GitLab REST API v4 (1008 operations) — the vendor's complete API surface, preserved as-is. See `gitlab_rest_api-latest.json` above for the curated subset if you just need common CRUD automation.

---

## Studio Projects

### GitLab Project

Backed by the **`GitLab REST API:latest`** Integration Model (see [`gitlab_rest_api-latest.json`](./OpenAPIs/gitlab_rest_api-latest.json) above). The project contains **133 workflows** organized into **21 folders**, one workflow per curated operation. All workflows follow the naming convention `<Operation> <Resource>` (e.g. `List Merge Requests`, `Trigger Pipeline`).

Note the `CI-CD Variables` folder name uses a hyphen rather than a slash — Itential Platform's project folder paths use `/` as a path separator, so a literal `/` in a folder name would be parsed as nested folders instead of one folder name.

#### Folder Structure

| Folder | Workflows | Scope |
|---|---|---|
| Groups | 7 | Group (+ list projects, list subgroups) |
| Members | 10 | Group Member, Project Member |
| Deploy Tokens | 8 | Group Deploy Token, Project Deploy Token |
| CI-CD Variables | 10 | Group Variable, Project Variable |
| Projects | 10 | Project (+ archive/unarchive/fork/delete-fork), Project Fork (list) |
| Jobs | 6 | Job (+ cancel/retry/play/trace) |
| Merge Requests | 10 | Merge Request (+ commits/diffs/merge/versions) |
| Pipelines | 9 | Pipeline (+ trigger/latest/cancel/retry/jobs/variables) |
| Pipeline Schedules | 5 | Pipeline Schedule |
| Protected Branches | 5 | Protected Branch |
| Tags | 8 | Tag, Protected Tag |
| Releases | 5 | Release |
| Environments | 6 | Environment (+ stop) |
| Deployments | 5 | Deployment |
| Deploy Keys | 5 | Deploy Key |
| Runners | 3 | Project Runner (list, enable, disable) |
| Branches | 6 | Branch (+ protect/unprotect) |
| Repository Files | 5 | Repository File (+ get raw) |
| Repository Browse | 2 | Repository Tree, Repository Comparison |
| Commits | 6 | Commit (+ diff, comments) |
| Users | 2 | User |

#### Dependencies

| Dependency | Notes |
|---|---|
| `GitLab REST API:latest` Integration Model | Import from [`gitlab_rest_api-latest.json`](./OpenAPIs/gitlab_rest_api-latest.json) before importing the project |
| `GitLab` integration instance | Create in **Admin > Integrations** with the connection properties above. Workflows are wired to an integration instance named `GitLab` — update the `adapter_id` value in each workflow task if yours is named differently |

**Testing status:** all 133 workflows were created and schema-validated against a running Itential Platform instance. `List Projects` and `List Groups` were executed against a real GitLab.com account and confirmed returning live data. `Get Project` for a specific project outside the token's granted scope failed with `insufficient_granular_scope` — GitLab's fine-grained personal access tokens can restrict `Project`/`Group` read access to a limited set of resources (e.g. "personal projects only"), independent of this Integration Model; a token with broader scope resolves this. The remaining workflows have not been individually executed.
Loading
Loading