Getting Started with GameFabric: Branches & Images

Welcome to Getting Started with GameFabric!

By the time you finish this fast-tracked 101, you’ll have a Branch in GameFabric with your first game server image pushed.

What you’ll need:

• A container image of your game server binary, built and ready to push. You can follow our documentation here if you haven’t done so already.

Branches are isolated Docker registries for storing your game server images and any other container in your orchestration stack, like sidecars. They’re available across all your Environments.

Rather than just organizing your images, Branches can also enforce release control:

• Structural Safety: Your live server fleets (Armadas) are locked to specific Branches. A development build can’t leak into a production fleet by accident.

• Deliberate Promotion: To move a tested build to the next stage (like Dev → QA → Prod) you explicitly promote it.

• Automatic Cleanup: Each branch has customizable retention policies that define it, like keeping only the last 10 builds. Your registry stays clean without any messy scripts.

Let’s get your first Branch created.

In your GameFabric UI, go to ‘Branches’ under the ‘Supply’ section in the leftward sidebar.

To create your Branch, click on the yellow button in the top right of the main panel (‘+ Create Branch’).

A box will open for you to get started in.

Give your new Branch a ‘Name’ that will be used to reference images. 

Then choose a ‘Display Name’ that identifies its purpose. 

You can fill in a description as well to make it clear to yourself and your team what this Branch will be used for.

Hit Next.

An Image Retention Policy controls how long images stay in the registry and how many tags are kept. Set it now. It’s easier than cleaning up later.

Enter a fitting name for the ‘Image Retention Policy Name’ field or just keep it as ‘default-policy’.

You’ll see some other optional fields, such as ‘Image Regex,’ and ‘Tag Regex,’ but we don’t need these right now. These are pattern filters used to target specific builds.

Scroll down to configure Keep Count and Keep Days. At least one must be greater than 0.

• Keep Count: always keep at least this many images, even if they’d otherwise be deleted by the day rule.

• Keep Days: delete images older than this many days.

The two rules work together. With Keep Count set to 10 and Keep Days set to 14 (the default policy), images older than 14 days are deleted, but the process stops if it would leave fewer than 10 images.

Click Next.

You’ll be shown a summary of your Branch and given a push URL.

You can find this URL at any time by clicking on ‘View Images’ in the main panel on your Branches page.

Click ‘Create Branch’ and ta da! You now have your first Branch in GameFabric.

${USERNAME} and ${PASSWORD} below are for your Service Account credentials. Replace them with those values. $URL is the push URL from the previous step.

If login should fail, confirm your Service Account exists and belongs to a group with push permissions (for example, default : image-providers)

Tag your image against the registry and push it.

${URL} is the same registry URL, and ${BRANCH} is the Branch Name you just created.

Two things to know about tags in GameFabric:

• Tags are immutable. Once pushed, a tag always refers to the exact same image. Pushing the same image:tag combination again fails. Use unique tags per build: semantic versions (v1.0.1), build identifiers (build-1234), or timestamps (dev-20260224-143052).

• The ‘:latest’ tag is rejected. Always tag explicitly.

On the Branches page in the main panel, find your created Branch and click on ‘View Images’.

Then, confirm your image appears in the list:

Now, your image is ready to select when creating a Vessel (long-lived game server) or Armada (session-based game servers).

Note: If you prefer to manage your promotions internally, you can simply have a branch per internal stage as well. You are not obligated to use image promotion.

Once an image is tested and ready for another branch (for example, moving from QA to production), you can promote it directly in the UI without having to re-push.

On the ‘Branches’ page, click ‘View Images’ on your created Branch. Find your image in the panel, click on the three-dot menu on the far right, and select Promote Image.

In the pop-up, select your target branch and optionally assign a new tag.

Click Save.

Your image is now available in the target Branch under the original tag, or the new tag if you assigned one.

Prefer the API? Image promotion is also available via the GameFabric API. You can read more about it here.

Congratulations! You’re now up and running with Branches and image pushing and promotion in GameFabric.

If you want more granular detail on Branches within GameFabric, you can read more in our official documentation.

Next: Getting Started with GameFabric: Vessels