OceanLaunch docs

Build, ship and run your apps

Deploying

API and CI deploys

Deploy from a CI job or a script, and read your apps and deployments, with a personal API token.

API tokens

Open the menu under your name and choose API tokens. Give the token a name and choose:

The token is shown once, when you create it. We keep only a fingerprint of it, so it can't be shown again: if you lose it, revoke it and make another.

A token acts as you, with your role in each workspace at the moment of each call. If you leave a workspace, your tokens lose access to it too. Revoking a token stops it at once. Creating and revoking tokens is recorded in your security log, and the list shows when each token was last used.

Keep tokens in your CI's secret store (for example a GitHub Actions secret), never in your repository.

Calls

The API is at https://portal.oceanlaunch.cloud/api/v1. Send the token on every call:

Authorization: Bearer <your token>
CallWhat it does
GET /meThe token's owner, whether it can deploy, and its workspace if it has one.
GET /workspacesYour workspaces: slug, name and your role.
GET /workspaces/{workspace}/appsThe workspace's apps: slug, name, status and address.
GET /workspaces/{workspace}/apps/{app}One app, with its newest deployment.
GET /workspaces/{workspace}/apps/{app}/deploymentsIts 20 newest deployments.
GET /workspaces/{workspace}/apps/{app}/deployments/{number}One deployment: status, commit, times and, if it failed, why.
POST /workspaces/{workspace}/apps/{app}/deploymentsDeploys the app again: the newest commit of its branch, or its latest upload. Needs a token that can deploy. Answers 202 with the new deployment.
GET /workspaces/{workspace}/apps/{app}/deployments/{number}/logs?after={id}Its build and deploy log, 500 lines at a time, oldest first. Pass the last line's id as after for the next ones; when finished is true and no lines come back, that's all.

The workspace and app are the slugs from their addresses in the dashboard. A deployment's status is one of queued, building, deploying, live, failed, cancelled or superseded.

Errors and limits

Errors come back as {"error": "…"} with:

Deploy from GitHub Actions

The command-line tool does this in one line and waits for the deployment to go live. Or call the API directly:

Save a Read and deploy token as a repository secret named OCEANLAUNCH_TOKEN, then add a step after your tests. Replace my-workspace and my-app with your slugs:

- name: Deploy to OceanLaunch
  env:
    OCEANLAUNCH_TOKEN: ${{ secrets.OCEANLAUNCH_TOKEN }}
  run: |
    curl --fail-with-body -X POST \
      -H "Authorization: Bearer $OCEANLAUNCH_TOKEN" \
      https://portal.oceanlaunch.cloud/api/v1/workspaces/my-workspace/apps/my-app/deployments

Apps connected through the GitHub App already deploy on every push to their branch; use the API when you want the deploy to wait for your tests, or for upload and image apps.