> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Workflow (GitHub Actions): automated deploy

# 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.



## 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.

```yaml
      - 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 from scratch; it **replaces** the files of the existing application (identified by the `SQUARECLOUD_APP_ID`) with the files contained within your `.zip` file.

### 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.

```yaml
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`: Your API token (found in your Square Cloud account settings).



## 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.