ComputeSphereLearn
Console
Learning paths / Deploy on ComputeSphere / Deploy as code

GitHub Actions: setup-csph and the deploy action

Reading · 7 min · Module 8, lesson 4 of 642 min left in this module

Module 8 · Deploy as codeLesson 4 of 6

Goal: Add a GitHub Actions workflow that deploys to ComputeSphere with a project-scoped token.

Key idea

A GitHub workflow can deploy for you: the same steps every time, from a known commit. It signs in with a Project access token kept in GitHub's secrets, so a leak can only reach one project.

GitHub Actions in five lines

  • A workflow is a YAML file in .github/workflows/ that runs when something happens, like a push.
  • A workflow has one or more jobs; each job runs on a runner, a fresh machine GitHub provides.
  • A job is a list of steps: a shell command (run:) or a ready-made action (uses:).
  • ${{ … }} fills in a value when the workflow runs, such as a secret.
  • Each run shows up in the repository's Actions tab, green or red.

The two actions

computesphere/deploy@v1 installs csph, signs in with your token, deploys and waits for Running. Most workflows need only this. computesphere/setup-csph@v1 only installs csph and signs it in, for when you want to run your own csph commands.

Step 1: a token with the least access

A workflow can't sign in with a browser, so it uses an API token. Tokens start with csph_, which makes a leaked one easy for secret scanners to spot. Choose Project access, limited to the one project the workflow deploys.

Make it an account token, so it keeps working if you leave the team. In the console, open Settings, then Accounts, choose the account and open its Tokens tab. Choose New token, name it, choose Project access, pick the project, set an expiry and choose Create token. It's shown once.

Step 2: store it in GitHub

In your repository, open Settings, then Secrets and variables, then Actions:

  • Under Secrets, add COMPUTESPHERE_API_TOKEN. Secrets are hidden in logs and can't be read back.
  • Under Variables, add COMPUTESPHERE_PROJECT_ID and COMPUTESPHERE_ENV_ID. IDs aren't secret; csph projects list and csph environments list --project <project-id> show them.

Never paste a token into the workflow file. Anything in the file is in your Git history.

Step 3: the workflow

name: Deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: deploy
        uses: computesphere/deploy@v1
        with:
          token: ${{ secrets.COMPUTESPHERE_API_TOKEN }}
          file: computesphere.yaml
          project: ${{ vars.COMPUTESPHERE_PROJECT_ID }}
          environment: ${{ vars.COMPUTESPHERE_ENV_ID }}
      - run: echo "Deployed ${{ steps.deploy.outputs.service-url }} (${{ steps.deploy.outputs.status }})"

workflow_dispatch adds a Run workflow button in the Actions tab; the lab adds a trigger on push. The action runs csph deploy, the same engine as csph apply.

Inputs and outputs
InputWhat it's for
tokenYour API token. Required. Always from a secret
fileThe manifest. computesphere.yaml by default
image, name, portDeploy a prebuilt image as one web service instead. Port 8080 by default
registry-url, registry-username, registry-passwordCredentials for a private image; the password from a secret
project, environmentWhere to deploy, as IDs
versionThe csph version to install. Pin one for repeatable runs
wait-timeoutHow long to wait for Running. 5m by default

Outputs: service-url, status (created, updated or unchanged), deployment-id (empty when several services deploy) and result, the full JSON.

A red job means a bad deploy

When a run deploys one service, the action waits for Running and fails the job if it doesn't get there within wait-timeout. A broken image turns the job red instead of reporting success while the old version serves. Leave no-wait off in CI. A manifest that changes several services doesn't wait, so check those with csph deployments list.

Check yourself

Your CI token leaks. Which scope keeps the damage smallest?
Running csph yourself with setup-csph

Use setup-csph once, then call csph directly. Its token is exported to later steps, so csph is already signed in:

      - uses: computesphere/setup-csph@v1
        with:
          token: ${{ secrets.COMPUTESPHERE_API_TOKEN }}
      - run: csph apply --file computesphere.yaml --project "$PROJECT" --environment "$ENV"
        env:
          PROJECT: ${{ vars.COMPUTESPHERE_PROJECT_ID }}
          ENV: ${{ vars.COMPUTESPHERE_ENV_ID }}

In the docs