From 8f8cc4d63d5ea2fb010dae026029efc377887e8c Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Thu, 11 Jun 2026 13:00:04 +0100 Subject: [PATCH] docs(cloud): Add Deploy from CI with GitHub Actions guide and retitle Redis guide --- cloud_docs/02-concepts/01-deployments.md | 2 +- .../02-concepts/06-personal-access-tokens.md | 2 +- cloud_docs/02-guides/05-redis.md | 17 ++- .../07-deploy-from-ci-with-github-actions.md | 137 ++++++++++++++++++ .../01-deployment/06-github-automation.md | 118 --------------- docusaurus.config.js | 4 + 6 files changed, 152 insertions(+), 128 deletions(-) create mode 100644 cloud_docs/02-guides/07-deploy-from-ci-with-github-actions.md delete mode 100644 cloud_docs/reference/01-deployment/06-github-automation.md diff --git a/cloud_docs/02-concepts/01-deployments.md b/cloud_docs/02-concepts/01-deployments.md index 27d199ff..d91bca8d 100644 --- a/cloud_docs/02-concepts/01-deployments.md +++ b/cloud_docs/02-concepts/01-deployments.md @@ -160,4 +160,4 @@ Common causes are missing dependencies in `pubspec.yaml` or compile errors in yo - [Deployment hooks](/cloud/concepts/deployment-hooks) for pre- and post-deploy automation. - [Handling private dependencies](/cloud/reference/deployment/handling-private-dependencies) for private package access during the build. - [Ship non-Dart files with your server](/cloud/guides/ship-non-dart-files) for shipping static assets like configuration and templates. -- [Automate deployment with GitHub Actions](/cloud/reference/deployment/github-automation) for CI/CD setups. +- [Deploy from CI with GitHub Actions](/cloud/guides/deploy-from-ci-with-github-actions) for shipping every push. diff --git a/cloud_docs/02-concepts/06-personal-access-tokens.md b/cloud_docs/02-concepts/06-personal-access-tokens.md index 477ee791..fe8eb015 100644 --- a/cloud_docs/02-concepts/06-personal-access-tokens.md +++ b/cloud_docs/02-concepts/06-personal-access-tokens.md @@ -131,7 +131,7 @@ Store the token as a repository secret, then pass it to the official action: token: ${{ secrets.SERVERPOD_CLOUD_TOKEN }} ``` -A full setup walkthrough lives in the [serverpod_cloud_deploy action README](https://github.com/serverpod/serverpod_cloud_deploy). +For the full walkthrough, see [Deploy from CI with GitHub Actions](/cloud/guides/deploy-from-ci-with-github-actions). ## Related diff --git a/cloud_docs/02-guides/05-redis.md b/cloud_docs/02-guides/05-redis.md index 7c40c7da..fb04ea94 100644 --- a/cloud_docs/02-guides/05-redis.md +++ b/cloud_docs/02-guides/05-redis.md @@ -1,14 +1,15 @@ --- -title: Redis (PubSub and caching) +sidebar_label: Use Redis for PubSub and caching +description: Configure a third-party Redis service like Upstash for distributed caching and PubSub across multiple Serverpod Cloud server instances. --- -# Redis (PubSub and caching) +# Use Redis for PubSub and caching Serverpod Cloud does not yet provide Redis natively. You can use a third-party Redis service and point your Serverpod app at it. This guide uses [Upstash](https://upstash.com) as an example; other Redis-compatible providers that support TLS and password auth will work with the same configuration pattern. Serverpod uses Redis for **distributed caching** and **PubSub** when running across multiple servers. The connection is configured via environment variables and a password. -## Prerequisites +## Before you start - Completed the **Installation** steps (`scloud` installed and authenticated). - A Serverpod Cloud project already deployed (or ready to deploy). @@ -70,9 +71,9 @@ scloud deploy After a successful deploy, your server will use Upstash for Redis-backed caching and PubSub. -## Related documentation +## Related -- [Serverpod configuration](https://docs.serverpod.dev/concepts/configuration) – Redis options and environment variables -- [Serverpod caching](https://docs.serverpod.dev/concepts/caching) – Local and Redis-backed caches -- [Upstash: Connect your client](https://upstash.com/docs/redis/howto/connectclient) – Connection details and TLS -- [Passwords, secrets, and environment variables](/cloud/concepts/passwords-secrets-env-vars) – How Serverpod Cloud injects passwords and variables +- [Serverpod configuration](https://docs.serverpod.dev/concepts/configuration) for Redis options and environment variables. +- [Serverpod caching](https://docs.serverpod.dev/concepts/caching) for local and Redis-backed caches. +- [Upstash: Connect your client](https://upstash.com/docs/redis/howto/connectclient) for connection details and TLS. +- [Passwords, secrets, and environment variables](/cloud/concepts/passwords-secrets-env-vars) for how Serverpod Cloud injects passwords and variables. diff --git a/cloud_docs/02-guides/07-deploy-from-ci-with-github-actions.md b/cloud_docs/02-guides/07-deploy-from-ci-with-github-actions.md new file mode 100644 index 00000000..77cb251c --- /dev/null +++ b/cloud_docs/02-guides/07-deploy-from-ci-with-github-actions.md @@ -0,0 +1,137 @@ +--- +sidebar_label: Deploy from CI with GitHub Actions +description: Use the official serverpod_cloud_deploy GitHub Action to deploy your Serverpod Cloud project on every push to your main branch. +--- + +# Deploy from CI with GitHub Actions + +Use the official [`serverpod/serverpod_cloud_deploy`](https://github.com/serverpod/serverpod_cloud_deploy) action to deploy your Serverpod Cloud project on every push. Setup takes about ten minutes once you have a personal access token. + +## Before you start + +- A personal access token. See [Create a token](/cloud/concepts/personal-access-tokens#create-a-token) on the Personal access tokens page. +- The project's `scloud.yaml` committed to the repository. It's created by `scloud launch` or `scloud link`. +- Either: generated Serverpod files committed to the repository, **or** a willingness to run `serverpod generate` in CI (covered as a variant below). +- One Serverpod project per repository, located no more than two subdirectory levels below the repository root. + +## Add the token as a repository secret + +In your GitHub repository, go to **Settings → Secrets and variables → Actions → New repository secret**. Name the secret `SERVERPOD_CLOUD_TOKEN` and paste the token value. + +Using `SERVERPOD_CLOUD_TOKEN` as the secret name matches the environment variable `scloud` reads, which keeps the workflow YAML clean. + +## Add the workflow file + +Create `.github/workflows/deploy.yml` with the following workflow: + +```yaml title=".github/workflows/deploy.yml" +name: Deploy to Serverpod Cloud + +on: + push: + branches: [main] + +permissions: + contents: read + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Flutter SDK + uses: subosito/flutter-action@v2 + + - name: Activate serverpod command + run: dart pub global activate serverpod_cli + + - uses: serverpod/serverpod_cloud_deploy@v1 + with: + token: ${{ secrets.SERVERPOD_CLOUD_TOKEN }} +``` + +What each step does: + +- The `actions/checkout@v4` step clones the repository into the runner. +- The `subosito/flutter-action@v2` step installs the Flutter SDK, which also provides Dart. The deploy action needs Dart to install `scloud`. +- The `dart pub global activate serverpod_cli` step puts the framework CLI on the runner so any pre-deploy hooks (for example, `serverpod generate`) can run. +- The `serverpod/serverpod_cloud_deploy@v1` step installs `scloud`, reads your `scloud.yaml`, and runs `scloud deploy` against your project using the token. + +## Push to trigger the workflow + +Commit the workflow file and push to `main`. Open the **Actions** tab in your repository to watch the run. When it succeeds, confirm the deploy went live: + +```bash +scloud deployment show +``` + +You should see a recent deployment moving through Upload → Cloud build → Infra deploy → Service rollout, finishing with the rocket on **Service rollout**. + +## Run `serverpod generate` in CI (variant) + +If you don't want to commit generated Serverpod files, run `serverpod generate` as a workflow step instead. The Flutter SDK in the workflow below provides the Dart toolchain `serverpod generate` needs and is also handy if the project's pre-deploy hook builds a Flutter web client. + +```yaml title=".github/workflows/deploy.yml" +name: Deploy to Serverpod Cloud + +on: + push: + branches: [main] + +permissions: + contents: read + +env: + # Replace with your Cloud project ID and the path to your server package. + PROJECT_ID: your-project-id + SERVER_DIR: ./path/to/server + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Flutter SDK + uses: subosito/flutter-action@v2 + + - name: Generate Serverpod code + working-directory: ${{ env.SERVER_DIR }} + run: | + dart pub get + dart pub global activate serverpod_cli + serverpod generate + + - uses: serverpod/serverpod_cloud_deploy@v1 + with: + token: ${{ secrets.SERVERPOD_CLOUD_TOKEN }} + project_id: ${{ env.PROJECT_ID }} + project_dir: ${{ env.SERVER_DIR }} +``` + +The `flutter-action@v2` step is required if the `generate` step pulls Flutter packages. Pass `project_id` and `project_dir` to the action so it knows which project to deploy and where the server code lives. + +## Action inputs + +| Input | Required | What it does | +| --------------------- | -------- | ----------------------------------------------------------------------------------------------- | +| `token` | yes | Your personal access token, passed from the repository secret. | +| `working_directory` | no | The directory the action runs in. Defaults to the repository root. | +| `project_id` | no | The Cloud project to deploy to. Inferred from `scloud.yaml` when present. | +| `project_dir` | no | Path to the server package. Useful for monorepos where the server isn't at the repository root. | +| `project_config_file` | no | Path to `scloud.yaml` if it's not in the default location. | + +## Troubleshooting + +**`scloud auth login` is required in the run output.** The `token` input is empty or the secret name in the workflow doesn't match what's in your repository's secrets. Confirm the secret is named `SERVERPOD_CLOUD_TOKEN` and the workflow references `${{ secrets.SERVERPOD_CLOUD_TOKEN }}`. + +**Project not found.** Either `scloud.yaml` isn't committed and the action can't resolve the project, or `project_id` was passed but doesn't match a project on your Cloud account. Commit `scloud.yaml`, or pass the correct `project_id` as an action input. + +**Generated files missing.** The primary workflow assumes generated Serverpod files are committed. Either commit them, or switch to the variant workflow that runs `serverpod generate` in CI. + +## Related + +- [Personal access tokens](/cloud/concepts/personal-access-tokens) for how to create and rotate tokens. +- [Deployments](/cloud/concepts/deployments) for the deploy lifecycle the action triggers. +- [Deployment hooks](/cloud/concepts/deployment-hooks) for tasks that should run before or after a deploy. diff --git a/cloud_docs/reference/01-deployment/06-github-automation.md b/cloud_docs/reference/01-deployment/06-github-automation.md deleted file mode 100644 index 6921560e..00000000 --- a/cloud_docs/reference/01-deployment/06-github-automation.md +++ /dev/null @@ -1,118 +0,0 @@ -# Deploying using GitHub Actions - -The [serverpod-cloud-deploy][] action can be used to automatically deploy projects on GitHub to Serverpod Cloud. - -[serverpod-cloud-deploy]: https://github.com/marketplace/actions/serverpod-cloud-deploy - - -## Usage - -This is a simple GitHub workflow example that uses this action. - -```yml -name: Automated Serverpod Cloud deploy - -on: - push: - branches: [main] - -permissions: - contents: read - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup Flutter SDK - uses: subosito/flutter-action@v2 - - - name: Activate serverpod command - run: dart pub global activate serverpod_cli - # Note: Does not pin the serverpod version, which you may want to do. - - - uses: serverpod/serverpod-cloud-deploy@v1 - with: - token: ${{ secrets.MY_SERVERPOD_CLOUD_ACCESS_TOKEN }} -``` - -Prerequisites: - * A GitHub secret has been set containing the access token - > (create a token with `scloud auth create-token`) - - * `serverpod generate` has been run and the generated files are committed - (or `serverpod generate` is included as a predeploy script in in `scloud.yaml`) - - * `scloud.yaml` is committed in the server package - > (create this file with `scloud launch` or `scloud link`) - - * The repository has only one Serverpod project and it is no more than two - subdirectory levels down from the root - - -## Inputs - -The action takes the following inputs: - -- Required: - - * `token`: Serverpod Cloud access token. - -- Optional: - * `working_directory`: Path to the action's working directory. - Default value is `.` - - * `project_id`: Cloud project ID. - - * `project_dir`: Path to the project's server directory. - - * `project_config_file`: Path to the project's configuration file. - - -## Combine with serverpod generate - -The following workflow example does not require the generated serverpod files -to be committed nor the scloud.yaml file to be available. - -```yml -name: Automated Serverpod Cloud generate & deploy -# Checks out the repository, sets up Flutter, runs serverpod generate, -# and deploys to Serverpod Cloud. - -on: - push: - branches: ["master","main"] - -permissions: - contents: read - -env: - # Change these values according to your project - PROJECT_ID: my-project-id - SERVER_DIR: ./packages/my_server - CLOUD_TOKEN: ${{ secrets.MY_SERVERPOD_CLOUD_ACCESS_TOKEN }} - -jobs: - generate-and-deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup Flutter SDK - uses: subosito/flutter-action@v2 - - - name: Run serverpod generate - working-directory: ${{ env.SERVER_DIR }} - run: | - dart pub get - dart pub global activate serverpod_cli - serverpod generate - # (generation can also be included as a predeploy script in in `scloud.yaml`) - - - uses: serverpod/serverpod-cloud-deploy@v1 - with: - token: ${{ env.CLOUD_TOKEN }} - project_id: ${{ env.PROJECT_ID }} - project_dir: ${{ env.SERVER_DIR }} -``` diff --git a/docusaurus.config.js b/docusaurus.config.js index 032e146d..9f1d2050 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -249,6 +249,10 @@ const config = { from: ['/cloud/reference/deployment/deployment-hooks'], to: '/cloud/concepts/deployment-hooks', }, + { + from: ['/cloud/reference/deployment/github-automation'], + to: '/cloud/guides/deploy-from-ci-with-github-actions', + }, ], }, ],