ConnectCloud Developers

Create an ownership (tenant:forge:write and maintainer, or tenant:forge:admin)

POST /api/forge/v1/projects/{key}/ownerships

Module: Forge · operationId: createForgeOwnership · Tag: Configuration · Auth: access token (Authorization: Bearer <accessToken>)

Requires tenant:forge:admin, or tenant:forge:write and project role maintainer or admin. Exactly one of ownerRef (a project member, at least developer) and ownerTeamId – or neither when parentId is set (the owner is inherited); the deputies are members with at least the developer role (400 ownerRef / ownerTeamId / deputyRefs). parentId nests the ownership (same project, no cycle, at most 4 levels, 400 parentId). itemTypes are item type keys and matchLabelIds plain labels (never owner::…). Creates the ownership's label owner::<key> in the same transaction (409 key_taken when the key or the label name exists). Writes forge.config.updated.

Parameters

Name In Type Required Description
key path string yes Project key (e.g. APP)

Request body

application/json (required)

  • deputyRefs (array of string): E-mails of the deputies
  • description (string): Description (max length 2000)
  • itemTypes (array of string): Item type keys
  • key (string): Create: key; fixed afterwards
  • matchLabelIds (array of string (uuid)): Plain labels (never owner::…)
  • name (string): Display name (max length 80)
  • ownerRef (string): E-mail of the owner person; empty clears it on PATCH
  • ownerTeamId (string): Owning team; empty clears it on PATCH
  • parentId (string): Parent ownership; empty clears it on PATCH
  • paths (array of string): Repository path patterns (see Ownership.paths)
  • version (integer): PATCH: the version the change is based on

Example:

{
  "deputyRefs": [
    "paul.schmid@muster-it.example"
  ],
  "description": "Kotlin-Code der Android-App.",
  "key": "android",
  "name": "Android-App",
  "ownerRef": "marie.wagner@muster-it.example",
  "parentId": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
  "paths": [
    "app/android/**"
  ]
}

Responses

  • 201 Created (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 409 Error (application/json)

Fields of the 201 answer:

  • deputyRefs (array of string, required): E-mails of the deputies (members, at least developer); need an owner of their own
  • description (string, required): Description (max length 2000)
  • id (string (uuid), required): Ownership id
  • itemTypes (array of string, required): Item type keys: items of these types belong here (without an owner:: label)
  • key (string, required): Key; never changes (its label is owner::<key>)
  • labelId (string (uuid), required): The ownership's label owner::<key>; items carry it and it wins over the matchers
  • matchLabelIds (array of string (uuid), required): Plain labels (never owner::…): items carrying one belong here (without an owner:: label); the later position wins
  • name (string, required): Display name (max length 80)
  • ownerRef (string, nullable, required): E-mail of the owner person (a member, at least developer); exclusive with ownerTeamId
  • ownerTeamId (string (uuid), nullable, required): The owning team; exclusive with ownerRef. Neither is allowed only with a parent (inherited)
  • parentId (string (uuid), nullable, required): The parent ownership (same project, no cycle, at most 4 levels); without an owner of its own the nearest ancestor's applies
  • paths (array of string, required): Repository path patterns, the CODEOWNERS subset: segments separated by /, * and ? within a segment, ** as a whole segment for any number of directories. A pattern without / (other than a trailing one) matches at any depth, one with / is relative to the root (a leading / anchors explicitly); a trailing / matches directories. A pattern whose last segment has no wildcard also matches everything below the directory it names (hr, /apps/github); one ending in a wildcard matches only what it names (docs/*). No character classes, \, !, # or spaces. Paths decide only for code (CODEOWNERS, scm).
  • position (integer, required): Precedence: a later ownership wins a path or an item both match
  • version (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

{
  "deputyRefs": [
    "paul.schmid@muster-it.example"
  ],
  "description": "Kotlin-Code der Android-App.",
  "id": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b02",
  "itemTypes": [],
  "key": "android",
  "labelId": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8c06",
  "matchLabelIds": [],
  "name": "Android-App",
  "ownerRef": "marie.wagner@muster-it.example",
  "ownerTeamId": null,
  "parentId": "df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01",
  "paths": [
    "app/android/**"
  ],
  "position": 3,
  "version": 1
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/ownerships' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"deputyRefs":["paul.schmid@muster-it.example"],"description":"Kotlin-Code der Android-App.","key":"android","name":"Android-App","ownerRef":"marie.wagner@muster-it.example","parentId":"df9a0b1c-2d3e-4f4a-9b12-9d0e1f2a3b01","paths":["app/android/**"]}'

View as Markdown · Interactive reference · OpenAPI