Workflow: What It Is and How to Use It on Square Cloud

In modern software development, agility is essential. The term Workflow refers to an automated sequence of processes that take your code from the repository to the production server. On Square Cloud, you can use GitHub Actions to automate your deployments, ensuring greater security and minimized downtime.

1. What Is a GitHub Workflow?

A Workflow is a configurable, automated process that will execute one or more jobs. It is defined by a YAML file in your repository (inside the .github/workflows folder) and is triggered by specific events, such as a "push", the creation of a "pull request", or the release of a new version (tag).

Core Components:

• Events (on): The trigger that starts the workflow (e.g., triggering when a v1.0 tag is created).
• Jobs: A set of steps that execute on the same runner.
• Steps: Individual tasks, such as installing dependencies, building code, or uploading files.

2. The External Build Strategy

One of the greatest advantages of using Workflows with Square Cloud is the ability to perform the build (compilation) outside of the hosting environment.

By building in GitHub Actions and sending only the final output (the package ready to run) to Square Cloud, you drastically reduce server CPU usage during updates and ensure your application comes back online almost instantly, since it will only need to run the start command. Dependencies are not reinstalled on commit: when package.json changes, delete node_modules (and package-lock.json, if you uploaded one) and restart.

3. Understanding the Square Deployment Step

The heart of the automation is the Square Cloud GitHub Action. Unlike a manual upload, this step works as a smart bridge between GitHub and Square Cloud's servers. The Action installs the Square CLI and facilitates interaction with the API, allowing you to make commits via the command line.

      - name: Deploy to Square Cloud
        uses: squarecloudofc/github-action@v2
        with:
          # Sends the zip as a direct commit to your application
          command: commit --file project.zip ${{ secrets.SQUARECLOUD_APP_ID }} --restart
          token: '${{ secrets.SQUARE_CLOUD_TOKEN }}'

How the commit Command Works:

When using the official action, the commit command does not create a new application: it extracts the .zip into the existing application (identified by the SQUARECLOUD_APP_ID) and overwrites files with the same path; files that are not in the zip stay there. To remove a file, delete it in the dashboard file manager.

Key Points of the Action:

• Encapsulation: The zip file, which you can generate prior to this workflow step, is sent via API. This ensures that only the files required for production (excluding raw source code or heavy caches) are transferred.
• Secure Authentication: Communication is validated using your SQUARE_CLOUD_TOKEN, acquired from the Square Cloud dashboard.
• The --restart flag: This parameter is crucial. By including it, Square Cloud understands that as soon as the commit upload finishes, the application should restart automatically to apply the changes, eliminating the need for manual intervention in the dashboard.

4. Practical Example: Automated Next.js Deployment

Below, we present a workflow example that prepares a Next.js application and deploys it to Square Cloud whenever a new version tag (e.g., v1.0.2) is published on GitHub.

name: "Deploy Nextjs app"

on:
  push:
    tags:
      - "v*" # Triggers the workflow on any tag starting with 'v'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Install dependencies
        run: npm install

      - name: Build project
        # Compiles Next.js and adjusts permissions for essential files
        run: npm run build && chmod -R 777 .next next.config.ts package.json

      - name: Compress files (Zip)
        # Creates a package with only what is necessary to run (excluding raw source code)
        run: zip -r project.zip package.json .next next.config.ts public -x ".next/cache/*"

      - name: Deploy to Square Cloud
        uses: squarecloudofc/github-action@v2
        with:
          # Sends the zip as a direct commit to your application
          command: commit --file project.zip ${{ secrets.SQUARECLOUD_APP_ID }} --restart
          token: '${{ secrets.SQUARE_CLOUD_TOKEN }}'

5. Configuring Secrets

To grant GitHub permission to upload files to your Square Cloud account, you must not write your tokens directly in your code. Instead, use GitHub Secrets:

1. In your repository, go to Settings > Secrets and variables > Actions > Repository Secrets.
2. Add SQUARECLOUD_APP_ID: Your application ID on Square Cloud.
3. Add SQUARE_CLOUD_TOKEN: create under My Account > Security an API key dedicated to CI, with the apps:deploy and files:read scopes and restricted to this application only. If it leaks, the damage stays in that application, and revoking it does not affect your other keys.

6. Beyond GitHub: The CI/CD Ecosystem

While GitHub Actions is the most tightly integrated tool, the concept of a Workflow is universal. Developers also use solutions like GitLab CI/CD or Jenkins to achieve similar results. The key is to always strive for automation to avoid human error and ensure that the production environment is a faithful mirror of what was tested and approved in development.

Updated on: 10/04/2026