Deploying from CI

A deployment token lets a CI pipeline (GitHub Actions, GitLab CI, or any other) push to d2o without anyone’s personal credentials. Each token can push to exactly one remote: an environment’s remote, or one app’s own remote. It keeps working when the person who created it leaves your organization.

Create a token

In the dashboard, open the environment’s Settings → Deployment tokens (or an app’s Settings for the app’s own remote) and choose Create deployment token. Copy the token straight away: it is shown once. With the CLI:

paas deploy-tokens create ci-main -e production
paas deploy-tokens create ci-admin -e production -a admin --expires 90

A token never expires unless you choose 30, 90 or 365 days when creating it.

Creating or revoking an Environment’s tokens requires manage access to the Environment; an app’s tokens require manage access to the app. App tokens are listed and revoked with -a <app> too. An app that builds from the Environment’s shared remote has no token of its own: create the token on the Environment instead.

Save the token in your CI as a secret named D2O_DEPLOY_TOKEN.

GitHub Actions

on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: git push "https://x-access-token:${{ secrets.D2O_DEPLOY_TOKEN }}@push.d2o.io/sources/acme/shop/production.git" HEAD:main

GitLab CI

deploy:
  stage: deploy
  variables:
    GIT_DEPTH: 0
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - git push "https://x-access-token:${D2O_DEPLOY_TOKEN}@push.d2o.io/sources/acme/shop/production.git" HEAD:main

Use the remote shown when you create the token. GIT_DEPTH: 0 and fetch-depth: 0 give the push the full history it needs.

Verify the deployment

Run your application’s tests before the push step and limit production credentials to the intended branch and job. A successful git push means d2o accepted the source; the build or rollout can still fail afterward. Inspect the Deployment until it reaches Live.

For a scripted gate, supply a separate account API token through your CI secret store (PAAS_API_URL and PAAS_API_TOKEN), then watch the deployment:

paas watch -o acme -p shop -e production -a web

A deployment token authenticates Git only and cannot run paas watch or paas manifest check. Account API tokens act with their owner’s permissions; see API Access & Automation. If several jobs can push concurrently, use paas watch --deploy DEPLOY_NUMBER for the specific push instead of following whichever deployment is newest. See deployment tracking.

When a repository is linked directly to GitHub or GitLab, d2o reports deployment status on the commit and can wait for the commit’s CI results. That is another option when you do not want a CI job to hold an account API token.

Rotate or revoke

To rotate, create a new token, update the CI secret, then revoke the old one. Revoking stops the token immediately:

paas deploy-tokens list -e production
paas deploy-tokens revoke ci-main -e production

Deployments made with a token show it as the pusher, for example “deployment token ci-main”. Promote-only environments don’t accept pushes, so they don’t offer deployment tokens.