GitHub Action: Push Repo to Cloudron App

Overview

This guide explains how to set up the GitHub Action: Cloudron Push to App to automatically push your application to a Cloudron instance app whenever you push changes to your GitHub repository.

As an example, you have a custom web application and want to deploy it to a Cloudron LAMP app whenever you push changes to your GitHub repository.

Example repository: cloudron-io/github-action-test-repo.

This repo contains a simple index.html, index.css and composer.json file and is configured to use the GitHub Action to push to a Cloudron app. You can copy the .github/workflows/deploy-to-cloudron.yaml file from this repository to your own repository to get started quickly. You will still need to set up the GitHub Secrets as described below.

• Action repository: cloudron-io/cloudron-push-to-app
• GitHub Marketplace: Cloudron Push to App

Setup Instructions

1. Create a Cloudron API Token with read-write permissions and save it, you will need it in the next step
2. Add the API Token as a GitHub Secret
   1. Go to your GitHub repository
   2. Navigate to Settings > Environments
   3. Create a new environment with a name of your choice (e.g., cloudron-deploy) - each environment is for one Cloudron instance
   4. In the newly created environment, click Add environment secret and add the following secrets:
      1. CLOUDRON_URL: The URL of your Cloudron instance (e.g., my.demo.cloudron.io)
      2. CLOUDRON_TOKEN: The API token you created in step 1
      3. CLOUDRON_APP_ID: The App ID of the Cloudron app where you want to deploy your application. You can find the App ID in the Cloudron dashboard when configuring the app in the URL. Alternatively, you can also use the location e.g., lamp or fully qualified domain name e.g., lamp.demo.cloudron.io
3. Create a GitHub Actions Workflow
   1. In your GitHub repository, create the folder .github/workflows if it doesn't already exist

      mkdir -p .github/workflows
      

   2. Create a new file named deploy-to-cloudron.yaml.yml in the .github/workflows folder with the following content:

      # this is the rule when the action will be triggered - see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
      # this rule triggers the action on every push to the main branch
      on:
        push:
          branches:
            - main
      jobs:
        # this is the job name definition - you can name it as you like
        deploy-to-cloudron-app:
          # this is the runner definition, you can think of this as the operating system where the job will run - here we use the ubuntu-latest
          runs-on: ubuntu-latest
          # the environment that we created in step 2
          environment: cloudron-deploy
          # the steps to execute in this job
          steps:
            # Name of the step and which action to use - here we checkout the repository code with https://github.com/actions/checkout
            - name: Checkout Repository
              uses: actions/checkout@v6
            # Name of the step and which action to use - here we use the Cloudron Push to App action
            - name: Cloudron Push to App
              uses: cloudron-io/cloudron-push-to-app@latest
              # the parameters/variables to pass to the action
              with:
                # secret CLOUDRON_URL that we created in step 2 for the environment cloudron-deploy
                CLOUDRON_TOKEN: "${{ secrets.CLOUDRON_URL }}"
                # secret CLOUDRON_TOKEN that we created in step 2 for the environment cloudron-deploy
                CLOUDRON_URL: "${{ secrets.CLOUDRON_TOKEN }}"
                # secret CLOUDRON_APP_ID that we created in step 2 for the environment cloudron-deploy
                CLOUDRON_APP_ID: "${{ secrets.CLOUDRON_APP_ID }}"
                # optional: specify the destination path in the Cloudron app where the files should be pushed - default is /app/data/public
                # the action will copy all files from the repository root to this destination path
                CLOUDRON_PUSH_DESTINATION: "/app/data/public"
                # optional: create a backup of the app before deploying - default is "true"
                CLOUDRON_CREATE_APP_BACKUP: "true"
      

4. Commit and push the changes to your GitHub repository
5. Monitor the GitHub Actions tab in your repository to see the deployment progress

Multiple Environments - Staging and Live

You can also create multiple environments for e.g., live and staging and have a different CLOUDRON_URL, CLOUDRON_TOKEN and CLOUDRON_APP_ID and use the environments in another workflow that only triggers on a specific branch e.g., develop.

This way you can have a staging and live deployment setup

Customizing GitHub Action

You can add more steps to the GitHub Actions workflow before the Cloudron Push to App step to prepare your application for deployment.

For example, if your application requires Composer dependencies to be installed, you can add a step to install the dependencies before pushing the app to Cloudron:

on:
  push:
    branches:
      - main
jobs:
  deploy-to-cloudron-app:
    runs-on: ubuntu-latest
    environment: my.cloudron.dev
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v6
      # Extra step to install composer dependencies
      - name: Install composer dependencies
        uses: php-actions/composer@v6
      - name: Cloudron Push to App
        uses: cloudron-io/cloudron-push-to-app@latest
        with:
          CLOUDRON_URL: "${{ secrets.CLOUDRON_TOKEN }}"
          CLOUDRON_TOKEN: "${{ secrets.CLOUDRON_URL }}"
          CLOUDRON_APP_ID: "${{ secrets.CLOUDRON_APP_ID }}"
          CLOUDRON_PUSH_DESTINATION: "/app/data/public"
          CLOUDRON_CREATE_APP_BACKUP: "true"