Worlds / Eng and it ops

GitLab API

A local GitLab with projects, merge requests, pipelines, approval rules and protected branches. Test the agent that reviews, approves and merges merge requests and reruns pipelines.

Base path: /api/v4
Auth: Personal access token (PRIVATE-TOKEN header), the world key
Endpoints: 17
Status: Active today

This reference previews the surface the GitLab world serves in the closed beta. Paths mirror the public GitLab API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_GITLAB_URL`	This world's origin followed by `/api/v4`
`WORLDS_API_KEY`	The world key, accepted wherever GitLab expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @gitbeaker/rest

import { Gitlab } from "@gitbeaker/rest";

const api = new Gitlab({
  host: process.env.WORLDS_GITLAB_URL,
  token: process.env.WORLDS_API_KEY,
});

const issues = await api.Issues.all({ projectId: 42, state: "opened" });

API reference

17 of 17

Projects

Repositories with visibility and namespace.

GET/api/v4/projectsList projects
POST/api/v4/projectsCreate a project
GET/api/v4/projects/{id}Get a project
GET/api/v4/projects/{id}/repository/treeList the repository tree

Fields · 5

`id`	integer	Project id
`path_with_namespace`	string	group/project
`visibility`	string	private, internal or public
`default_branch`	string	Default branch
`open_issues_count`	integer	Open issues

Issues

Issues with labels, milestones and assignees.

GET/api/v4/projects/{id}/issuesList project issues
POST/api/v4/projects/{id}/issuesCreate an issue
PUT/api/v4/projects/{id}/issues/{iid}Update an issue
POST/api/v4/projects/{id}/issues/{iid}/notesComment on an issue

Fields · 5

`iid`	integer	Issue id inside the project
`title`	string	Title
`state`	string	opened or closed
`labels`	array	Labels
`assignees`	array	Assigned users

Merge requests

Merge requests, approvals and merge state.

GET/api/v4/projects/{id}/merge_requestsList merge requests
POST/api/v4/projects/{id}/merge_requestsCreate a merge request
PUT/api/v4/projects/{id}/merge_requests/{iid}Update a merge request
POST/api/v4/projects/{id}/merge_requests/{iid}/approveApprove a merge request
PUT/api/v4/projects/{id}/merge_requests/{iid}/mergeMerge a merge request

Fields · 6

`iid`	integer	Merge request id inside the project
`title`	string	Title
`state`	string	opened, merged or closed
`source_branch`	string	Source branch
`target_branch`	string	Target branch
`merge_status`	string	can_be_merged or cannot_be_merged

Pipelines

CI runs and their jobs.

GET/api/v4/projects/{id}/pipelinesList pipelines
POST/api/v4/projects/{id}/pipelineCreate a pipeline
POST/api/v4/projects/{id}/pipelines/{pipeline_id}/retryRetry failed jobs
GET/api/v4/projects/{id}/pipelines/{pipeline_id}/jobsList pipeline jobs

Fields · 5

`id`	integer	Pipeline id
`status`	string	running, success, failed and more
`ref`	string	Branch or tag
`sha`	string	Commit sha
`created_at`	datetime	Creation time

Test workflow

Prepare. Select the GitLab setup for your workflow and review its starting records, including projects, issues, merge requests.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

!214 merged
Only the flaky job on !219 retried
!221 still opened
!223 and !224 unchanged
No new deployment to production

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · GitLab
version: 2
connector: gitlab
seed: gitlab-starter
mode: isolated
policy: >
  Merge MRs on platform/billing that have a passing pipeline and every
  approval rule met. Retry only the job marked flaky on !219. Do not merge
  anything touching payment keys.
tasks:
  - id: merge-mrs-once-the-pipeline-passes-and-approval-rules-are-met
    prompt: Merge MRs once the pipeline passes and approval rules are met
  - id: retry-failed-pipeline-jobs-that-are-known-flaky
    prompt: Retry failed pipeline jobs that are known flaky
  - id: triage-issues-with-labels-and-milestones
    prompt: Triage issues with labels and milestones
expected:
  - "!214 merged"
  - "Only the flaky job on !219 retried"
  - "!221 still opened"
  - "!223 and !224 unchanged"
  - No new deployment to production
scenarios:
  - not-mergeable
  - sha-mismatch
  - rate-limited

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`not-mergeable`	PUT /merge returns 405 while approvals are missing
`sha-mismatch`	Merging with a stale sha returns 409
`rate-limited`	The API returns 429 past the user limit
`token-expired`	The project access token expires mid run
`stuck-pipeline`	A job stays pending with no runner

Starting data

Start each run from the same records and relationships. The overview below describes the GitLab starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
projects	3 projects in one group with protected main branches
merge requests	25 opened, draft, merged and closed
pipelines	Pipelines succeeded, failed, running and pending
approval rules	Backend and Security rules with required approvers
issues	50 with labels, weights and milestones

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Projects records

Projects

Repositories with visibility and namespace.

Field	Type	Meaning / relationship
`id`	integer	Project id
`path_with_namespace`	string	group/project
`visibility`	string	private, internal or public
`default_branch`	string	Default branch
`open_issues_count`	integer	Open issues

json · illustrative record shape

{
  "id": 1,
  "path_with_namespace": "<group/project>",
  "visibility": "<private, internal or public>",
  "default_branch": "<Default branch>",
  "open_issues_count": 1
}

See projects operations

Issues records

Issues

Issues with labels, milestones and assignees.

Field	Type	Meaning / relationship
`iid`	integer	Issue id inside the project
`title`	string	Title
`state`	string	opened or closed
`labels`	array	Labels
`assignees`	array	Assigned users

json · illustrative record shape

{
  "iid": 1,
  "title": "<Title>",
  "state": "<opened or closed>",
  "labels": [],
  "assignees": []
}

See issues operations

Merge requests records

Merge requests

Merge requests, approvals and merge state.

Field	Type	Meaning / relationship
`iid`	integer	Merge request id inside the project
`title`	string	Title
`state`	string	opened, merged or closed
`source_branch`	string	Source branch
`target_branch`	string	Target branch
`merge_status`	string	can_be_merged or cannot_be_merged

json · illustrative record shape

{
  "iid": 1,
  "title": "<Title>",
  "state": "<opened, merged or closed>",
  "source_branch": "<Source branch>",
  "target_branch": "<Target branch>",
  "merge_status": "<can_be_merged or cannot_be_merged>"
}

See merge requests operations

Pipelines records

Pipelines

CI runs and their jobs.

Field	Type	Meaning / relationship
`id`	integer	Pipeline id
`status`	string	running, success, failed and more
`ref`	string	Branch or tag
`sha`	string	Commit sha
`created_at`	datetime	Creation time

json · illustrative record shape

{
  "id": 1,
  "status": "<running, success, failed and more>",
  "ref": "<Branch or tag>",
  "sha": "<Commit sha>",
  "created_at": "<Creation time>"
}

See pipelines operations

See the GitLab world in the catalog