Deploy your Extend app with GitHub Actions

Last updated on October 27, 2026

Overview

If you host your Extend app source on GitHub, you can deploy it automatically with the official Deploy Extend App workflow. It's a ready-made GitHub Actions template. You copy one file into your repository, add a few settings, and every push to main builds and deploys your app.

push to main  →  build image  →  push to app registry  →  deploy  →  wait for rollout

The workflow runs AGS CLI on a standard GitHub-hosted runner. You don't install or host anything. The AccelByte/setup-ags-cli action installs and signs in to AGS CLI for you, so the workflow file stays short and easy to read.

Use it when you want hands-free, repeatable deploys instead of running AGS CLI manually.

info

The template lives in the AccelByte/extend-github-actions-template repository. This page walks you through the setup. The template README is the complete reference.

note

New to GitHub Actions? A workflow is a YAML file that GitHub runs automatically when something happens, such as a push to main. Each run happens on a fresh, temporary machine called a runner, so nothing is installed on your computer. You commit the file, and GitHub does the rest.

Before you begin

You need:

• An existing Extend app. The workflow deploys to an app. It doesn't create one. Create the app first in the Admin Portal or with AGS CLI.
• A Dockerfile in the root of your repository. The workflow uses the repository root as the build context.
• A confidential IAM client with the permissions below. Keep a copy of the client ID and client secret. To create the client, see Manage access control for applications.

Assign these permissions to the IAM client:

Cloud type	Permissions
AGS Private Cloud	ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ], ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ], ADMIN:NAMESPACE:{namespace}:EXTEND:DEPLOYMENT [CREATE]
AGS Public Cloud	Extend > Extend app image repository access (Read), Extend > App Management (Read), Extend > Deployment Management (Create)

These are the minimum permissions the workflow needs. They let it read the app, get registry credentials, and create a deployment. They can't create, update, or delete the app.

Set it up

Setup takes a few minutes.

1. Copy deploy-extend-app.yml from the template repository to .github/workflows/deploy-extend-app.yml in your repository. Commit it to your default branch. If you started from an official Extend sample app, the file may already be there.

2. In your GitHub repository, go to Settings > Secrets and variables > Actions > Variables. Add these repository variables:

   Variable	Description	Example
   AGS_BASE_URL	Your AGS environment base URL	https://dev.yourstudio.accelbyte.io
   AGS_NAMESPACE	The namespace your app lives in	yourgame
   EXTEND_APP_NAME	The name of your existing Extend app	guild-service

3. Go to Settings > Secrets and variables > Actions > Secrets. Add these repository secrets:

   Secret	Description
   AGS_CLIENT_ID	Your IAM client ID
   AGS_CLIENT_SECRET	Your IAM client secret

4. Push a commit to main. Open the Actions tab in your repository to watch the first deploy.

warning

Add the client ID and secret as secrets, never as variables. GitHub doesn't mask repository variables in logs.

note

The workflow triggers on pushes to a branch named main. If your default branch has a different name, either rename it to main or change branches: [main] at the top of the workflow file.

If anything is missing, the first step of the workflow fails within seconds. The error names what's missing and where to set it.

What the workflow does

Each run goes through these steps:

Step	What it does
Check configuration	Confirms all variables and secrets are set, and that the image tag is valid.
Setup AGS CLI	Uses the AccelByte/setup-ags-cli action to install AGS CLI, cache it, and log in with your IAM client.
Build and push image	Runs ags extend image-upload to build your image for linux/amd64 and push it to your app's registry. The image tag is the commit SHA.
Deploy and wait for rollout	Runs ags extend deploy-app and waits until the rollout finishes or the wait limit passes.
Summary	Writes the app, namespace, image tag, AGS CLI version, and result to the run page, so you can read the outcome without opening the logs.

The deploy step sets the run result. A failed deploy turns the run red. The summary reports one of these results:

Result	Meaning
deployed	The rollout completed and the app is healthy.
failed	The rollout failed. Check the app logs before you retry.
timed out	The wait limit passed while the rollout was still in progress. The deployment isn't cancelled.
did not run	An earlier step failed, so the deploy step never started.

warning

A timeout doesn't roll back your deployment. The rollout may still finish. Check the app status in the Admin Portal before you redeploy, so you don't stack a second rollout on top of one that's still running.

Customize the workflow

The workflow file is yours to edit. The env: block at the top holds the values you're most likely to change:

Variable	Default	Description
AGS_VERSION	latest	The AGS CLI version to install.
WAIT_LIMIT	600	Seconds to wait for the rollout before giving up. Raise it if your app is slow to start.
WAIT_INTERVAL	10	Seconds between rollout status checks.
IMAGE_TAG	Commit SHA	The tag applied to the built image.

By default, the workflow uses the latest AGS CLI release, so CLI fixes reach you without any edits. The trade-off is that re-running an old commit installs today's CLI, not the version that commit was first deployed with. If you need reproducible builds, pin an exact version, for example AGS_VERSION: '0.5.3'. You then need to bump the version yourself when you want a newer CLI.

To run your tests before any image is built, uncomment the Test step in the workflow and point it at your test command. If the command fails, the workflow stops before it builds or pushes anything.

The workflow also runs one deploy at a time per app, and stops a stuck job after 30 minutes. Keep the concurrency and timeout-minutes settings. They protect your app from overlapping rollouts.

Deploy manually or roll back

You can also run the workflow on demand. In your repository, go to Actions > Deploy Extend App > Run workflow, then choose a branch or tag.

To roll back:

1. Tag the last known-good commit, or create a branch on it.
2. Run the workflow and select that tag or branch.
3. Leave the Image tag field empty.

The workflow checks out that version, rebuilds it, and deploys it with that commit's SHA as the image tag.

warning

The Image tag field only labels the image. It doesn't choose what to build. If you run the workflow against main and type an older SHA, it builds the current main and tags it with the older SHA. Use the branch or tag selector to pick what to deploy.

Troubleshoot

Symptom	Cause and fix
Missing repository variable or Missing secret	A variable or secret isn't set. The message names which one and where to set it.
Authentication fails in the Setup AGS CLI step	Confirm the IAM client type is Confidential, not Public, and that AGS_BASE_URL points to the right environment.
Deploy rejected as unauthorized	The IAM client is missing a permission. Compare it against the list in Before you begin.
Image builds, but the app never becomes healthy	The app usually crashes at startup, often because of a missing environment variable. Check the app logs in the Admin Portal.
exec format error in the app logs	The image architecture doesn't match the cluster. Keep --platform linux/amd64 in the build step, and use a base image that supports it.

To check your configuration, authentication, and connectivity outside of CI, run ags doctor locally against the same base URL and IAM client.

Security tips

• Treat AGS_CLIENT_SECRET as a long-lived credential. Rotate it regularly and when team members leave.
• Grant only the permissions listed in Before you begin, scoped to a single namespace.
• Never move credentials from secrets to variables.

For the full reference, including version pinning with Renovate, see the template README.