API

Déployer depuis la CI

Un workflow GitHub Actions complet qui déploie et attend le résultat, avec les scopes nécessaires.

La raison la plus courante de détenir une clé API : un push sur main doit redéployer l’application, et le pipeline doit échouer si le déploiement échoue.

La clé qu’il faut

Exactement deux scopes : project:apps:deploy et project:deployments:view.
projectIds fixé au seul projet qu’elle déploie.
Si vos runners ont des adresses de sortie stables, allowedIps également. Une clé qui nomme sa sortie vaut bien moins une fois volée.

Stockez le secret dans le coffre de votre CI — jamais dans le dépôt. Voir frapper une clé.

Une étape GitHub Actions, de bout en bout

YAML

# .github/workflows/deploy.yml
- name: Deploy to DockBoard
  env:
    DOCKBOARD_URL: https://panel.example.com
    DOCKBOARD_API_KEY: ${{ secrets.DOCKBOARD_API_KEY }}
  run: |
    dep=$(curl -fsS -X POST "$DOCKBOARD_URL/api/deployments" \
      -H "Authorization: Bearer $DOCKBOARD_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"applicationId":"'"$APP_ID"'"}' | jq -r .id)

    # Poll until it settles.
    while :; do
      status=$(curl -fsS "$DOCKBOARD_URL/api/deployments/$dep" \
        -H "Authorization: Bearer $DOCKBOARD_API_KEY" | jq -r .status)
      case "$status" in
        RUNNING) echo "deployed"; break ;;
        FAILED|CANCELLED|ROLLED_BACK) echo "deploy $status"; exit 1 ;;
        *) sleep 5 ;;
      esac
    done

Rien ici n’est spécifique à GitHub hormis la syntaxe des secrets — les mêmes vingt lignes fonctionnent sur GitLab CI, Woodpecker ou un simple script shell.

Lire le statut

Statut	Signification
`PENDING` `BUILDING` `DEPLOYING`	En cours — continuez à interroger.
`RUNNING`	Succès. C’est l’état final favorable — il n’existe pas de `SUCCEEDED` distinct.
`FAILED` `CANCELLED` `ROLLED_BACK`	Échec définitif. Faites échouer le pipeline.

Traitez tous les statuts finaux, pas seulement le favorable. Une boucle qui ne sort que sur RUNNING tourne jusqu’au timeout du job quand un build échoue — le pire signal possible, car un timeout ressemble à un problème d’infrastructure plutôt qu’à un commit cassé.

Ce qui est réellement déployé

L’appel ci-dessus déploie la branche configurée de l’application à son HEAD, ce qu’on attend d’un workflow déclenché par un push.

commitSha sert au rollback, pas à épingler un nouveau build. Il est résolu contre l’historique de déploiement de cette application : un SHA jamais déployé donne un 400 plutôt qu’un déploiement silencieux du HEAD.

Si votre objectif est une copie en ligne par pull request plutôt qu’un déploiement de main, ce sont les environnements de préview qu’il vous faut — DockBoard les crée et les détruit lui-même, sans aucun câblage CI.