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:
- Workspace: all your workspaces, or just one. Limit it to one when you can.
- Access: Read only (list apps and deployments) or Read and deploy.
- Expires after: 7, 30 or 90 days, or a year. Every token expires; make a new one before then.
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>
| Call | What it does |
|---|---|
GET /me | The token's owner, whether it can deploy, and its workspace if it has one. |
GET /workspaces | Your workspaces: slug, name and your role. |
GET /workspaces/{workspace}/apps | The workspace's apps: slug, name, status and address. |
GET /workspaces/{workspace}/apps/{app} | One app, with its newest deployment. |
GET /workspaces/{workspace}/apps/{app}/deployments | Its 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}/deployments | Deploys 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:
401: no token, or it's mistyped, revoked or expired;403: the token is read only and the call deploys;404: the workspace, app or deployment doesn't exist, or the token can't see it;409: the deploy can't start, for example the trial ended or an upload app has no file yet;429: over 120 calls a minute with one token, or too many calls with a wrong token from one address.
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.