Connecting GitHub Actions to Edge Deploy

For a small team, the value is easy to see: the merge remains the release event, while the deployment steps become repeatable. Symbiosis runs deployments across 12 PoPs distributed globally, so the application reaches the edge without someone needing to start a manual release from their laptop.

Here is the workflow we are aiming for:

name: Deploy to Symbiosis

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Deploy to Symbiosis
        env:
          GSB_API_TOKEN: ${{ secrets.GSB_API_TOKEN }}
        run: gsb deploy

      - name: Check deployment status
        env:
          GSB_API_TOKEN: ${{ secrets.GSB_API_TOKEN }}
        run: gsb status

This example assumes the gsb CLI is available to the runner. If your workflow needs an installation step, add the installation method used by your project before the deploy step. The important pieces are the main branch trigger, the GitHub secret, and the gsb deploy command.

1. Connect GitHub to your Symbiosis project

Start by connecting the repository you want to deploy. Symbiosis uses GitHub OAuth for repository linking, so the first step is to authorize the connection and select the repository. This establishes the relationship between the GitHub repository and the Symbiosis project.

If you are starting from the command line, the relevant CLI commands are:

gsb init
gsb link

gsb init initializes the project locally. gsb link links that project to the repository and deployment target you connected through GitHub. You can use gsb status to inspect the current project state before adding automation.

At this point, you can already deploy from a local checkout with:

gsb deploy

That local path is useful while setting up the project. The rest of this article moves the same deployment action into GitHub Actions.

2. Add the deployment token as a GitHub secret

Create a repository secret named GSB_API_TOKEN in GitHub and add the API token used by the Symbiosis CLI. Keep the token in GitHub Secrets rather than placing it directly in the workflow file or committing it to the repository.

The workflow exposes the secret only to the commands that need it:

env:
  GSB_API_TOKEN: ${{ secrets.GSB_API_TOKEN }}

Use the same environment variable for both gsb deploy and gsb status. The token gives the workflow permission to perform the deployment, so repository access and secret management should be reviewed with the same care as any other CI credential.

3. Trigger deployment only from the release branch

The push trigger in the example is limited to main. For a pull request workflow, that means a merged PR creates the push event that starts the deployment. Changes pushed to feature branches do not deploy through this workflow.

This is a useful default for teams that treat merging to main as the release decision. It also keeps the workflow easy to understand: GitHub checks out the repository, provides the token, runs gsb deploy, and then checks the deployment status.

A four-person team setting this up for the first time might use this exact sequence. One engineer connects the repository through GitHub OAuth. Another adds GSB_API_TOKEN to the repository secrets. The team commits the workflow under .github/workflows/deploy.yml, opens a small pull request, and merges it after review. The resulting push to main starts the job, giving the team a single deployment path they can inspect in the GitHub Actions run.

What Actions adds to the deployment path

The basic Symbiosis integration does not require YAML pipeline configuration. Connect the repository, and a deploy webhook can trigger on push. For many projects, that is all the automation needed.

GitHub Actions is the option for teams that want more control around the deployment command. You can place checks before gsb deploy, restrict deployment to a branch, require particular jobs to pass, or make the deployment part of a larger workflow. The example above shows only the deployment portion, but the workflow can sit after the tests and checks your repository already runs.

The boundary is important: the simple git-push integration handles repository pushes through the connected deployment setup, with no workflow file required for a basic deploy. The GitHub Actions integration puts the deployment inside a GitHub workflow, where the branch trigger, preceding jobs, permissions, and secret usage are explicit.

When not to use GitHub Actions

Do not add Actions just because a deployment can use it. If pushing to the connected repository already gives you the behavior you want, the simple git-push integration is enough. It has fewer moving parts and no workflow YAML to maintain.

Choose GitHub Actions when the team needs deployment to follow repository checks or when the release path needs conditions that a direct push trigger does not provide. Otherwise, start with the simpler integration and move to Actions when the extra control becomes useful.

Verify the first deployment

After merging the workflow, open the GitHub Actions run and confirm that the deploy step completes. If you need to inspect the project from a local environment, use:

gsb status

You can also deploy directly during development with gsb deploy. Once the workflow is working, the normal path is straightforward: review the pull request, merge it to main, and let GitHub Actions run the Symbiosis deployment automatically.