Publish a Sandbox Template with GitHub Actions-Function Compute(FC)-阿里云帮助中心

FC Agent Sandbox provides an official GitHub template repository, aliyun-fc/fce2b-template-builder. After you create your own repository from this template, you only need to maintain a Dockerfile. GitHub Actions automatically builds a linux/amd64 image and pushes it to your private GHCR package, builds a Sandbox template from that image, creates a Sandbox to run a smoke test, and finally outputs a ready-to-use Template ID.

Build a Sandbox Template from a GHCR Custom Image requires you to push the image to GHCR yourself and then call the SDK to build the template. This document integrates template publishing into GitHub Actions, which fits scenarios where you want to manage the template definition in Git and publish a new template version with every code commit.

Use cases

The template definition (Dockerfile and dependencies) is version-controlled together with your business code, and every commit automatically publishes a new template version.
Team members do not need to install Docker or the SDK locally; publishing is done by committing code or by a manual trigger on GitHub.
Images are stored in a private GHCR package that cannot be pulled anonymously, and all build artifacts are governed by your own GitHub account.

Supported regions

Region	Region ID
China (Hong Kong)	`cn-hongkong`
Singapore	`ap-southeast-1`
US (Virginia)	`us-east-1`
US (Silicon Valley)	`us-west-1`

API Keys are isolated per region, and each publish targets a single region.

Prerequisites

FC Agent Sandbox is enabled, and you have the API Key for the target region.
You have a GitHub account with permission to create repositories.

Step 1: Create your repository

On the aliyun-fc/fce2b-template-builder repository page, click Use this template in the upper-right corner and select Create a new repository.

After the repository is created, modify the Dockerfile in the root directory as needed. Before you commit, make sure the Dockerfile can build a linux/amd64 image.

Step 2: Create a GitHub token

Create a GitHub Personal Access Token (classic) with the following scopes:

read:packages
write:packages

The user that owns the token must have read and write access to the repository and its private GHCR package. If the organization has SSO enabled, you must also authorize the token for the organization.

Step 3: Configure GitHub Actions credentials

Go to Settings → Secrets and variables → Actions of your repository.

Add the following Secrets:

Name	Description
`FCE2B_API_KEY`	The FC Agent Sandbox API Key for the target region.
`GHCR_TOKEN`	The GitHub token created in the previous step.

Add the following Variables:

Name	Example	Description
`FCE2B_REGION`	`us-west-1`	The target region where the template is created.

When you change FCE2B_REGION, you must also replace FCE2B_API_KEY with the API Key of that region.

Step 4: Publish the template

Trigger a publish in either of the following ways:

Modify and commit the Dockerfile, dependency files, or files under the landing directory to the master branch;
Go to Actions → Build fce2b template → Run workflow and trigger it manually.

A full run usually takes about 1 to 3 minutes, depending on the region and the image size.

Step 5: Get the result

After a successful run, check the corresponding GitHub Actions run:

Summary: the Template ID, Build ID, Sandbox ID, image address, and verification result;
Artifacts → landing-result: download the complete landing.json.

Save the Template ID. You can then use the E2B SDK to create Sandboxes from this template.

Update the template

After you modify the Dockerfile or dependencies, trigger the workflow again. Every successful publish generates a new Template ID and never overwrites previous templates; to roll back, keep using the old Template ID.

You can also publish a versioned image with a Git tag:

git tag v1.0.0
git push origin v1.0.0

Pushing the tag automatically builds a linux/amd64 image and publishes it to:

ghcr.io/<owner>/<repository>:v1.0.0

A version tag does not overwrite latest. To publish a new version, create a new Git tag.

Credential maintenance

Do not write FCE2B_API_KEY or GHCR_TOKEN into repository files, the Dockerfile, or Action logs.
Keep GHCR_TOKEN valid so that FC Agent Sandbox can continue to pull your private GHCR image.
After rotating the token, update GHCR_TOKEN and publish the template again.
After rotating the API Key or switching regions, update FCE2B_API_KEY and publish the template again.

FAQ

GHCR login or push returns 401/403: Check that GHCR_TOKEN has the read:packages and write:packages scopes, and that the token owner can access the repository. If the repository belongs to an organization, also check SSO authorization.
The API Key is rejected: Check that the API Key is valid for the target region and matches FCE2B_REGION.
The workflow does not run automatically: Automatic triggers only watch Dockerfile, dependency, workflow, and landing files on the master branch. You can also run it manually from the Actions page.
The template is created but the image cannot be pulled later: Check that the GHCR package stays private, that GHCR_TOKEN has not expired, and that the token owner still has read access to the package; then update the token and publish the template again.