Deploy from CI

If your pipeline, not a push, should decide when an app deploys, give it a deploy key. A deploy key works for one app and can do five things: plan a definition, deploy it, export the app's live definition, read the app's deployments, and generate the app's client types. It cannot approve a deployment, change a setting, read data or run anything.

Issue a deploy key

The app owner issues keys from the app's Deployments › Deploy keys. Name it after what will use it ("GitHub Actions, production"), and choose how long it lasts: 90 days by default, a year at most. The key is shown once; store it as a secret in your CI. The list shows when each key was last used, and revoking a key takes effect on its next use.

Use one key per app. With a staging app and a production app, give each environment of your CI its own key.

Plan

definition-plan says what deploying would do and changes nothing. Plan the connected repository at a commit, or upload the bundle from your checkout.

curl -s "$AUTHORIC_API/platform/autocrud/apps/actions/definition-plan" \
  -H "Authorization: Bearer $AUTHORIC_DEPLOY_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"targetAppUid\": \"$AUTHORIC_APP\", \"source\": \"repo\", \"sha\": \"$GITHUB_SHA\"}"

The answer carries summary (a count per group), groups (the plan in plain language), needs_approval (what would wait for a person) and plan_hash.

To plan the files in your checkout instead, send "source": "upload" and "files": an array of { "path", "content" }, with paths relative to the bundle folder.

Deploy

definition-deploy takes the same source and queues a deployment. It answers at once with the deployment; poll deployment-get with its uid until it settles.

uid=$(curl -s "$AUTHORIC_API/platform/autocrud/apps/actions/definition-deploy" \
  -H "Authorization: Bearer $AUTHORIC_DEPLOY_KEY" -H "Content-Type: application/json" \
  -d "{\"targetAppUid\": \"$AUTHORIC_APP\", \"source\": \"repo\", \"sha\": \"$GITHUB_SHA\"}" | jq -r .deployment.uid)

curl -s "$AUTHORIC_API/platform/autocrud/apps/actions/deployment-get" \
  -H "Authorization: Bearer $AUTHORIC_DEPLOY_KEY" -H "Content-Type: application/json" \
  -d "{\"targetAppUid\": \"$AUTHORIC_APP\", \"deploymentUid\": \"$uid\"}" | jq .deployment.status

needs_approval is a normal outcome, not a failure: the deployment waits for an approver in Authoric, and your pipeline can stop there.

GitHub Actions

Plan on every pull request, deploy on every push to main:

name: Authoric
on:
  pull_request:
  push:
    branches: [main]
jobs:
  authoric:
    runs-on: ubuntu-latest
    environment: production
    env:
      AUTHORIC_API: ${{ vars.AUTHORIC_API }}
      AUTHORIC_APP: ${{ vars.AUTHORIC_APP }}
      AUTHORIC_DEPLOY_KEY: ${{ secrets.AUTHORIC_DEPLOY_KEY }}
    steps:
      - name: Plan
        if: github.event_name == 'pull_request'
        run: |
          curl -sf "$AUTHORIC_API/platform/autocrud/apps/actions/definition-plan" \
            -H "Authorization: Bearer $AUTHORIC_DEPLOY_KEY" -H "Content-Type: application/json" \
            -d "{\"targetAppUid\": \"$AUTHORIC_APP\", \"source\": \"repo\", \"sha\": \"${{ github.event.pull_request.head.sha }}\"}"
      - name: Deploy
        if: github.event_name == 'push'
        run: |
          curl -sf "$AUTHORIC_API/platform/autocrud/apps/actions/definition-deploy" \
            -H "Authorization: Bearer $AUTHORIC_DEPLOY_KEY" -H "Content-Type: application/json" \
            -d "{\"targetAppUid\": \"$AUTHORIC_APP\", \"source\": \"repo\", \"sha\": \"$GITHUB_SHA\"}"

If you deploy from CI, turn off Deploy on push for the app, so a push does not deploy twice.

GitLab CI

authoric:deploy:
  stage: deploy
  image: curlimages/curl
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - >
      curl -sf "$AUTHORIC_API/platform/autocrud/apps/actions/definition-deploy"
      -H "Authorization: Bearer $AUTHORIC_DEPLOY_KEY" -H "Content-Type: application/json"
      -d "{\"targetAppUid\": \"$AUTHORIC_APP\", \"source\": \"repo\", \"sha\": \"$CI_COMMIT_SHA\"}"

Export

definition-export returns the app's live definition as bundle files ([{ path, content }]), the starting point for putting a console-built app into a repository.