Déployez sur Square Cloud depuis GitHub Actions

À chaque push, release ou lancement manuel, l’action officielle installe la CLI Square Cloud sur le runner, la vérifie et envoie votre code vers votre application.

Voir sur GitHub MarketplaceLa configurer en trois étapes
Fonctionne sur les runners Linux, Windows et macOS, en x64 et arm64. Le code source est disponible sur GitHub.

Déployez à chaque push en trois étapes

Deux valeurs enregistrées dans votre dépôt et un fichier de workflow. Ensuite, chaque push sur main envoie le code vers votre application et la redémarre.

  1. 1

    Enregistrez la clé d’API

    Créez une clé d’API dans les paramètres de sécurité de votre compte et enregistrez-la dans le dépôt comme secret SQUARECLOUD_API_KEY.

  2. 2

    Enregistrez l’ID de l’application

    Copiez l’ID depuis la page de l’application dans le tableau de bord et enregistrez-le comme variable de dépôt SQUARECLOUD_APP_ID.

  3. 3

    Ajoutez le workflow

    Committez le fichier ci-dessous sous .github/workflows/deploy.yml. Le prochain push sur main déploie votre application.

.github/workflows/deploy.yml
name: Deployon:  push:    branches: [main]jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • Gardez l’étape de checkout

    Sans actions/checkout, le runner n’a aucun fichier à envoyer.

  • Arrêtée ? Elle démarre aussi

    --restart redémarre l’application après l’envoi et la démarre si elle était arrêtée. Sans lui, les nouveaux fichiers ne sont pris en compte qu’au prochain redémarrage.

  • L’ID peut rester dans le dossier

    Sans ID, commit lit la ligne ID= du squarecloud.app du dossier, s’il existe : commit --restart suffit alors.

Ce que fait l’action sur le runner

Quatre étapes, dans cet ordre, sur chaque runner. Si l’une d’elles échoue, l’étape du workflow échoue aussi : un déploiement qui n’a pas eu lieu n’apparaît jamais en vert.

  1. 1

    Télécharge la build du runner

    Elle choisit la release de la CLI adaptée au système et au processeur du runner : la plus récente, ou la version que vous fixez. Les runners auto-hébergés la gardent dans leur cache d’outils.

  2. 2

    La vérifie avant de l’installer

    Le SHA-256 du téléchargement est comparé au checksums.txt de la release. Un fichier qui ne correspond pas n’est jamais installé ni lancé.

  3. 3

    Transmet la clé sans l’enregistrer

    La clé est masquée dans les logs et définie comme SQUARECLOUD_API_KEY pour le reste du job. Rien n’est écrit sur le disque du runner.

  4. 4

    Lance votre commande

    squarecloud suivi de votre command est lancé dans workdir. Si la commande échoue, l’étape échoue.

Un workflow pour chaque façon de livrer

Quatre modèles tirés de la documentation de l’action, prêts à copier. Les lignes surlignées sont celles qui changent par rapport au workflow ci-dessus.

  • Staging et production

    Les push sur main vont en production et ceux sur develop en staging, chacun vers sa propre application.

    • Le bouton Run workflow de l’onglet Actions déploie la branche de votre choix
    • concurrency fait attendre les déploiements d’une même branche au lieu de les superposer
    .github/workflows/deploy.yml
    name: Deployon:  push:    branches: [main, develop]  workflow_dispatch:concurrency:  group: deploy-${{ github.ref_name }}jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ github.ref_name == 'main' && vars.PRODUCTION_APP_ID || vars.STAGING_APP_ID }} --restart

  • Plusieurs applications dans un dépôt

    Chaque dossier est une application à part entière. Une matrice les déploie côte à côte, un job par dossier.

    • workdir dirige chaque déploiement vers son dossier
    • fail-fast: false évite qu’un déploiement en échec annule les autres
    .github/workflows/deploy.yml
    name: Deployon:  push:    branches: [main]jobs:  deploy:    runs-on: ubuntu-latest    strategy:      fail-fast: false      matrix:        include:          - folder: bot            app: ${{ vars.BOT_APP_ID }}          - folder: website            app: ${{ vars.WEBSITE_APP_ID }}    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          workdir: ${{ matrix.folder }}          command: commit ${{ matrix.app }} --restart

  • Déployez à la publication d’une release

    Seul le code d’une release publiée arrive sur l’application.

    • Les push et les releases en brouillon ne déploient pas
    .github/workflows/deploy.yml
    name: Deployon:  release:    types: [published]jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • Variables d’environnement depuis les secrets

    Gardez tokens et mots de passe dans les secrets GitHub et envoyez-les à l’application avant chaque déploiement. env set ajoute ou met à jour uniquement les variables indiquées, et le redémarrage après le commit les charge.

    • Depuis la CLI 3.1.1, les valeurs contenant des espaces ou des caractères comme $, &, ; ou | arrivent exactement telles qu’enregistrées dans le secret
    • Avec la CLI 3.1.0, entourez vous-même chaque valeur de guillemets simples
    • Passer les secrets par env garde leurs valeurs hors du script que GitHub lance
    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    install-only: true- name: Update environment variables  run: squarecloud app env set --app "$APP_ID" "DISCORD_TOKEN=$DISCORD_TOKEN" "DATABASE_URL=$DATABASE_URL"  env:    APP_ID: ${{ vars.SQUARECLOUD_APP_ID }}    DISCORD_TOKEN: ${{ secrets.DISCORD_TOKEN }}    DATABASE_URL: ${{ secrets.DATABASE_URL }}- run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

Cinq inputs

Seul token est obligatoire. Les autres ont des valeurs par défaut que vous pouvez garder.

tokenObligatoire
Votre clé d’API Square Cloud. Gardez-la dans un secret, jamais dans le fichier du workflow.
command
La commande de la CLI à lancer, sans le préfixe squarecloud, par exemple commit --restart. Sans elle, l’action installe seulement la CLI.
versionPar défaut latest
La version de la CLI à installer : latest, ou 3.1.0 et au-delà. Trouver la dernière version n’appelle pas l’API GitHub, dont la limite de requêtes ne gêne donc jamais.
workdirPar défaut .
Le dossier dans lequel la commande est lancée, relatif à la racine du dépôt.
install-onlyPar défaut false
Installe seulement la CLI et définit la clé, pour que les étapes suivantes du job lancent squarecloud elles-mêmes.

  • Fixez la version de la CLI

    Déploie le dossier bot toujours avec la CLI 3.1.1, quelle que soit la dernière release.

    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    version: 3.1.1    workdir: bot    command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • Lancez plusieurs commandes

    Avec install-only, la CLI et sa clé restent disponibles pour les étapes suivantes : build, déploiement, puis statut en JSON.

    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    install-only: true- run: npm ci && npm run build- run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart- run: squarecloud app status ${{ vars.SQUARECLOUD_APP_ID }} --json

Tous les runners GitHub

L’action est testée sur les runners Linux, Windows et macOS de GitHub, en x64 et arm64. Vos runners auto-hébergés fonctionnent aussi, à condition que leur version prenne en charge les actions node24.

  • Linux

    x64 et arm64 sur les runners hébergés par GitHub. Sur vos propres runners, aussi x86 ou ARMv7.

    • Testée sur ubuntu-latest et ubuntu-24.04-arm

  • Windows

    x64 et arm64 sur les runners hébergés par GitHub. Sur vos propres runners, aussi x86.

    • Testée sur windows-latest et windows-11-arm

  • macOS

    Intel et Apple silicon, sur les runners hébergés par GitHub comme sur les vôtres.

    • Testée sur macos-latest

Votre clé reste secrète

L’action traite la clé d’API comme le mot de passe qu’elle est.

  • Masquée dans les logs

    La clé est enregistrée comme secret avant que quoi que ce soit ne soit lancé : elle s’affiche en *** dans chaque ligne de log.

  • Jamais sur le disque

    La CLI la lit dans SQUARECLOUD_API_KEY. Elle n’est ni enregistrée sur le runner ni passée en ligne de commande.

  • Limitée à un job

    Les étapes suivantes du même job peuvent l’utiliser, les autres jobs non. Lancez les actions dont vous n’êtes pas sûr dans un job séparé.

  • Une clé par dépôt

    Donnez à chaque dépôt sa propre clé, pour en révoquer une sans toucher aux autres.

Une CLI pensée pour les workflows

Chaque commande lancée par l’action est une commande de la CLI Square Cloud, et la CLI est conçue pour fonctionner sans terminal.

  • Confirmez avec -y

    Les commandes qui modifient ou suppriment des données demandent une confirmation. Un workflow ne peut pas répondre : ajoutez -y, sinon la commande s’arrête avec le code 1 sans rien changer.

  • Sortie en JSON

    Les commandes qui affichent des données acceptent --json, pour une sortie que l’étape suivante peut lire.

  • Suivez chaque requête

    Définissez SQUARECLOUD_DEBUG: 1 dans le env de l’étape pour journaliser la méthode, le chemin, le statut et la durée de chaque requête à l’API, jamais les en-têtes ni les corps.

  • Choisissez ce qui part

    commit exclut ce que liste squarecloud.ignore, en syntaxe gitignore. node_modules, .git et les lockfiles restent exclus, sauf si vous les réincluez avec !.

Vous utilisez déjà @v2 ?

@v2 pointe désormais vers la nouvelle version : votre workflow continue de fonctionner sans changement. Voici ce qui a changé.

  • workdir est appliqué. Jusqu’à la 2.1.2, il était ignoré et les commandes étaient lancées à la racine du dépôt.
  • La clé n’est plus passée en ligne de commande ni enregistrée sur le runner.
  • Les runners Windows, macOS et arm64 sont pris en charge.
  • Le téléchargement de la CLI est vérifié avec ses sommes de contrôle, et le nouvel input version fixe la version.
  • Trouver la dernière CLI n’appelle plus l’API GitHub : la limite de requêtes de l’API ne l’affecte plus.
  • L’action tourne sur Node 24.

La CLI 3.1 exclut aussi les lockfiles des envois. Pour continuer à envoyer le vôtre, ajoutez !package-lock.json (ou votre lockfile) à squarecloud.ignore.

Ressources associées

Un plan pour chaque étape de votre projet

Commencez petit et évoluez quand vous en avez besoin, sans contrat d’engagement.

Comparer tous les plans

4,9 sur 5 · 402 avis sur Google + TrustpilotTrustpilot

Hébergé dans un datacenter partenaire disposant des certifications
Tier 3ISO 27001SOC 2 Type IIProtection DDoS permanente
Découvrez notre infrastructure

Prêt à faire évoluer votre projet ?

Rejoignez les plus de 500 000 développeurs qui ont utilisé Square Cloud pour héberger leurs projets.

Commencez dès maintenant sur Square CloudVoir les plans et les tarifs
  • Tarifs prévisibles
  • Aucune surprise de facturation
  • Déployez en quelques secondes
  • Haute disponibilité
  • Évoluez en toute stabilité
  • Redémarrage automatique
  • SSL et sécurité inclus
  • Conteneurs isolés