From 5f93beb91e37479ecad298459f2b23caa4f08f0d Mon Sep 17 00:00:00 2001 From: Sebastian Fox Date: Wed, 29 Apr 2026 12:44:32 +0200 Subject: [PATCH 1/3] docs: add API example for image promotion between branches --- src/multiplayer-servers/api/examples.md | 52 +++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/src/multiplayer-servers/api/examples.md b/src/multiplayer-servers/api/examples.md index 2d027e16..02a11972 100644 --- a/src/multiplayer-servers/api/examples.md +++ b/src/multiplayer-servers/api/examples.md @@ -26,6 +26,58 @@ curl -X 'GET' \ Take note of the Image object name, since that is what you need to reference in the Vessel specification for the next step. +## Promoting an image to another branch + +Image promotion allows you to move a container image from one branch to another (for example, from `dev` to `prod`) after it has been tested. This is a two-step process: first, you find the internal name of the image you want to promote, then you create an `ImagePromotion` resource targeting the destination branch. + +### Step 1: Find the image's internal name + +Use the `fieldSelector` query parameter to filter images by their image name and tag. This returns the internal object name you need for the promotion request. + +```bash +curl -X 'GET' \ + "https://${GAMEFABRIC_URL}/api/container/v1/images/scopes/${SOURCE_BRANCH}?fieldSelector=spec.image=${IMAGE_NAME},spec.tag=${IMAGE_TAG}" \ + -H 'Accept: application/json' \ + -H "Authorization: Bearer ${GF_API_TOKEN}" | jq '.items[].metadata.name' +``` + +This returns the internal name of the image (for example, `simple-game-server-cwgpftt`). You need this value for the next step. + +### Step 2: Create the ImagePromotion + +Create an `ImagePromotion` resource in the target branch, referencing the source branch and the internal image name from step 1. + +```bash +curl -X 'POST' \ + "https://${GAMEFABRIC_URL}/api/container/v1/imagepromotions/scopes/${TARGET_BRANCH}" \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${GF_API_TOKEN}" \ + -d '{ + "apiVersion": "container/v1", + "kind": "ImagePromotion", + "metadata": { + "name": "'"$(uuidgen)"'", + "branch": "'"${TARGET_BRANCH}"'" + }, + "spec": { + "branch": "'"${SOURCE_BRANCH}"'", + "imageName": "'"${INTERNAL_IMAGE_NAME}"'" + } +}' +``` + +| Variable | Description | +|----------|-------------| +| `SOURCE_BRANCH` | The branch the image currently exists in (for example, `dev`) | +| `TARGET_BRANCH` | The branch to promote the image to (for example, `prod`) | +| `IMAGE_NAME` | The human-readable image name (for example, `simple-game-server`) | +| `IMAGE_TAG` | The tag of the image (for example, `0.39`) | +| `INTERNAL_IMAGE_NAME` | The internal object name returned from step 1 | + +::: tip +See the API reference for [listing images](/api/multiplayer-servers/apiserver#tag/container.v1.Image/operation/listImage) and [creating image promotions](/api/multiplayer-servers/apiserver#tag/container.v1.ImagePromotion/operation/createImagePromotion) for full details on available fields and responses. +::: + ## Creating a Vessel In this first example, let's create a Vessel using the REST API. From 214a50230228f93c40c251f791dd74748153c672 Mon Sep 17 00:00:00 2001 From: Sebastian Fox Date: Wed, 29 Apr 2026 14:53:59 +0200 Subject: [PATCH 2/3] docs: use jq -r and capture image name into variable for copy-pasteable workflow --- src/multiplayer-servers/api/examples.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/multiplayer-servers/api/examples.md b/src/multiplayer-servers/api/examples.md index 02a11972..b83f166b 100644 --- a/src/multiplayer-servers/api/examples.md +++ b/src/multiplayer-servers/api/examples.md @@ -35,13 +35,13 @@ Image promotion allows you to move a container image from one branch to another Use the `fieldSelector` query parameter to filter images by their image name and tag. This returns the internal object name you need for the promotion request. ```bash -curl -X 'GET' \ +INTERNAL_IMAGE_NAME=$(curl -X 'GET' \ "https://${GAMEFABRIC_URL}/api/container/v1/images/scopes/${SOURCE_BRANCH}?fieldSelector=spec.image=${IMAGE_NAME},spec.tag=${IMAGE_TAG}" \ -H 'Accept: application/json' \ - -H "Authorization: Bearer ${GF_API_TOKEN}" | jq '.items[].metadata.name' + -H "Authorization: Bearer ${GF_API_TOKEN}" | jq -r '.items[0].metadata.name') ``` -This returns the internal name of the image (for example, `simple-game-server-cwgpftt`). You need this value for the next step. +This captures the internal name of the image (for example, `simple-game-server-cwgpftt`) into the `INTERNAL_IMAGE_NAME` variable for use in the next step. ### Step 2: Create the ImagePromotion From 5ea8d794684d2009c0941dc022e5e76c2e807c2a Mon Sep 17 00:00:00 2001 From: Sebastian Fox Date: Mon, 4 May 2026 16:46:41 +0200 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20address=20PR=20feedback=20=E2=80=94?= =?UTF-8?q?=20improve=20intro,=20add=20permissions=20note,=20fix=20heading?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/multiplayer-servers/api/examples.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/multiplayer-servers/api/examples.md b/src/multiplayer-servers/api/examples.md index b83f166b..fb7719b1 100644 --- a/src/multiplayer-servers/api/examples.md +++ b/src/multiplayer-servers/api/examples.md @@ -28,9 +28,13 @@ Take note of the Image object name, since that is what you need to reference in ## Promoting an image to another branch -Image promotion allows you to move a container image from one branch to another (for example, from `dev` to `prod`) after it has been tested. This is a two-step process: first, you find the internal name of the image you want to promote, then you create an `ImagePromotion` resource targeting the destination branch. +Image promotion enables you to copy a container image from one branch to another without manual intervention, reducing the risk of human error. It allows teams to validate an image in a staging or testing environment and, once it meets the required quality standards, promote it to production. -### Step 1: Find the image's internal name +This approach eliminates the need for users to manually pull, tag, and push images—operations that are error-prone, particularly in multi-platform contexts or when handling multiple image versions. By avoiding mistakes such as selecting or tagging the wrong image, image promotion provides a safer and more reliable mechanism for testing and releasing images. + +### Step 1: Find the internal image name + +You need a service account with POST permission on IMAGEPROMOTIONS for image promotions and GET permission on IMAGES to access the image resources. Use the `fieldSelector` query parameter to filter images by their image name and tag. This returns the internal object name you need for the promotion request.