feat: environments + env sync API (#579)

Co-authored-by: Rihan <[email protected]>
Co-authored-by: Hugo Richard <[email protected]>

Author: 3 people

docs/content/changelog/environments.md

@@ -0,0 +1,123 @@
+---
+title: Environments & Improved variable management
+description: "Create additional deployment environments & revamped environment variable management"
+date: 2025-06-06
+image: '/images/changelog/nuxthub-environments.png'
+authors:
+  - name: Rihan Arfan
+    avatar:
+      src: https://avatars.githubusercontent.com/u/20425781?v=4
+    to: https://bsky.app/profile/rihan.dev
+    username: rihan.dev
+  - name: Ahad Birang
+    avatar:
+      src: https://avatars.githubusercontent.com/u/2047945?v=4
+    to: https://bsky.app/profile/farnabaz.dev
+    username: farnabaz.dev
+---
+
+::tip
+This feature is available on both [free and pro plans](/pricing) and in [`@nuxthub/core >= v0.9.0`](https://github.com/nuxt-hub/core/releases/tag/v0.9.0).
+::
+
+We've been working hard on closing the gap between Pages and Workers, and improving the experience using NuxtHub. With this release, we've brought preview environments to Workers, and improved environment variables management.
+
+## Environments
+
+When we first introduced Cloudflare Workers support in NuxtHub, we only supported production deployments. Today, we're excited to announce that Workers now has the same powerful environment capabilities as Pages, making it easier than ever to test and deploy your applications. Any deployment from a non-production branch automatically gets deployed to the preview environment with separate resources (database, kv, etc.) than production.
+
+::note
+Due to Cloudflare limitations, deployments with the `cloudflare_durable` preset will not receive a unique deployment URL.
+::
+
+### Custom Environments
+
+We're taking things a step further and introducing the ability to create additional environments beyond just preview and production, such as staging, testing, etc. All environments in NuxtHub have unique resources, making them perfect for testing. NuxtHub allows configuring the branch patterns on custom environments with exact, prefix and suffix, to enable different workflows.
+  - Example: The branch `staging` deploys to the staging environment
+  - Example: All branches starting with `bugfix/` deploys to a testing environment
+
+Get started from the new "Environments" page of NuxtHub Admin.
+
+## Revamped environment variables management
+
+The biggest challenge faced by users since introducing the NuxtHub GitHub Action as the primary method for deployment was syncing environment variables and secrets to GitHub. Our syncing relied on [environments in GitHub](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment), which is a paid feature, therefore many NuxtHub users had to manually set environment variables to GitHub. Furthermore, GitHub Actions required specifying every secret used within the workflow which meant there was friction when using secrets, such as `NUXT_UI_PRO_LICENSE`.
+
+We've worked hard to resolve this hurdle and to streamline the experience using NuxtHub. Now we're thrilled to introduce [`nuxt-hub/action@v2`](https://github.com/nuxt-hub/action), which now securely pulls environment variables and secrets from NuxtHub Admin, and builds your Nuxt application. On top of this, you can now scope environment variables to be build or runtime only, allowing you to further protect secrets.
+
+### Migration guide
+
+In order to use the new system, follow our migration guide:
+
+1. Update to [`@nuxthub/core >= v0.9.0`](https://github.com/nuxt-hub/core/releases/tag/v0.9.0) on production and preview
+2. Go to Environment Variables within the NuxtHub Admin
+3. Click "Migrate environment variables"
+
+#### Migrating to NuxtHub Action v2
+
+1. Remove the `environments:` section
+2. Remove the `Build application` section
+3. Upgrade from `nuxt-hub/action@v1` to `nuxt-hub/action@v2`
+
+See the updated GitHub Action workflow below:
+```diff
+name: Deploy to NuxtHub
+on: push
+
+jobs:
+  deploy:
+    name: "Deploy to NuxtHub"
+    runs-on: ubuntu-latest
+-    environment:
+-      name: ${{ github.ref == 'refs/heads/main' && 'production' || 'preview' }}
+-      url: ${{ steps.deploy.outputs.deployment-url }}
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+-      - name: Ensure NuxtHub module is installed
+-        run: pnpx nuxthub@latest ensure
+-
+-      - name: Build application
+-        run: pnpm build
+
+-      - name: Deploy to NuxtHub
+-        uses: nuxt-hub/action@v1
+-        id: deploy
+-        with:
+-          project-key: <YOUR-PROJECT-KEY>
+
++      - name: Build & Deploy to NuxtHub
++        uses: nuxt-hub/action@v2
++        with:
++          project-key: <YOUR-PROJECT-KEY>
+```
+
+4. If your Nuxt app is not within the repository root and `directory:` parameter is provided, remove the trailing `/dist`.
+```diff
+-      - name: Deploy to NuxtHub
+-        uses: nuxt-hub/action@v1
+-        with:
+-          directory: frontend/dist
+
++      - name: Build & Deploy to NuxtHub
++        uses: nuxt-hub/action@v2
++        with:
++          directory: frontend
+```
+
+This release marks a significant milestone in our journey to provide a seamless deployment experience across both Pages and Workers. The introduction of preview environments and improved environment variables management brings feature parity between the two platforms, making it easier than ever to deploy and test your Nuxt applications. We're excited to see how you'll use these new capabilities to streamline your development workflow.

docs/content/docs/1.getting-started/3.deploy.md

@@ -90,7 +90,7 @@ NUXT_HUB_PROJECT_KEY=<my-project-key> NUXT_HUB_USER_TOKEN=<my-user-token> npx nu
 
 This will authenticate your user and link your NuxtHub project for deployment.
 
-::note 
+::note
 For security, **do not hardcode these values**. Instead, store them as environment variables in your CI/CD pipeline.
 ::
 
@@ -130,9 +130,6 @@ jobs:
   deploy:
     name: "Deploy to NuxtHub"
     runs-on: ubuntu-latest
-    environment:
-      name: ${{ github.ref == 'refs/heads/main' && 'production' || 'preview' }}
-      url: ${{ steps.deploy.outputs.deployment-url }}
     permissions:
       contents: read
       id-token: write
@@ -143,23 +140,19 @@ jobs:
       - name: Install pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 9
+          version: 10
 
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: 'pnpm'
 
       - name: Install dependencies
         run: pnpm install
 
-      - name: Build application
-        run: pnpm run build
-
-      - name: Deploy to NuxtHub
-        uses: nuxt-hub/action@v1
-        id: deploy
+      - name: Build & Deploy to NuxtHub
+        uses: nuxt-hub/action@v2
 ```
 ::
 
@@ -170,8 +163,12 @@ jobs:
 The following input parameters can be provided to the GitHub Action. Learn more about [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith) on GitHub's documentation.
 
 ::field-group
-  ::field{name="directory" type="string" default="dist"}
-    The directory of the built Nuxt application. Defaults to `dist`.
+  ::field{name="directory" type="string" default=""}
+    The directory of the Nuxt application to build.
+  ::
+
+  ::field{name="output-directory" default="dist"}
+    The output directory containing the built Nuxt application to deploy, relative to the directory specified in `directory`.
   ::
 
   ::field{name="project-key" type="string"}
@@ -203,32 +200,21 @@ The GitHub Action provides the following outputs that you can use in subsequent
     - https://example.nuxt.dev (main)
     - https://feat-example.example.pages.dev (feat/example)
   ::
-::
 
-### Environment Variables & Secrets
+  ::field{name="environment-url" type="string"}
+    The permanent URL of the environment.
 
-NuxtHub automatically copies all your project's environment variables to your GitHub repository actions environment variables.
-
-When encrypting an environment variable in the NuxtHub Admin, a GitHub actions secret will be created in your repository.
-
-You can view the environment variables and secrets synchronized by NuxtHub by navigating to **Repository Settings -> Secrets and variables -> Actions** on GitHub.
-
-::warning
-If you have a private repository on a free GitHub account or organization, NuxtHub won't be able to sync the env variables & secrets as GitHub repository environments (production / preview) are not available. In this case, you must manually set up the environment variables by navigating to **Repository Settings -> Secrets and variables -> Actions** on GitHub.
+    Examples:
+    - https://hello-world-staging.example.workers.dev ('staging' environment)
+  ::
 ::
 
-In order to use GitHub Actions variables and secrets, you need to update your workflow to expose them as environment variables:
+### Environment Variables & Secrets
 
-```diff [.github/workflows/nuxthub.yml]
-  - name: Build application
-    run: pnpm run build
-+   env:
-+     NUXT_PUBLIC_VAR: ${{ vars.NUXT_PUBLIC_VAR }}
-+     NUXT_UI_PRO_LICENSE: ${{ secrets.NUXT_UI_PRO_LICENSE }}
-```
+The NuxtHub GitHub Action builds the Nuxt application using build-time environment variables and secrets specified within NuxtHub Admin.
 
-::note
-This is mostly useful for build-time environment variables.
+::tip
+You can scope variables to only be available during build-time, This is useful in cases such as `NUXT_UI_PRO_LICENSE`.
 ::
 
 ### Setup
@@ -300,8 +286,8 @@ The `NUXT_HUB_PROJECT_KEY` is used later in [Configure Projects for GitLab](#con
 workflow:
   auto_cancel:
     on_job_failure: all
-    
-variables: 
+
+variables:
   APP_PATH: "PATH/TO/YOUR/APP"
   NUXT_HUB_PROJECT_KEY: "YOUR_NUXT_HUB_PROJECT_KEY"
 
@@ -320,11 +306,11 @@ deploy_project:
     # you can not use node_modules from cache, since nuxthub needs write access
     - bun install
     # if you set up your variables correctly this should deploy successfully
-    - bunx nuxthub deploy 
+    - bunx nuxthub deploy
   rules:
     # here we configure auto deploy on branch: staging and main
     - if: '$CI_COMMIT_BRANCH == "staging" || $CI_COMMIT_BRANCH == "main"'
-      
+
 manual_deploy_project:
   stage: deploy
   image: "oven/bun:slim"
@@ -394,7 +380,7 @@ trigger_project_b:
     strategy: depend
     include:
       - local: "apps/project-bar/.gitlab-ci.yml"
-  
+
 add_manual_triggers:
   stage: trigger_apps
   trigger:
@@ -437,7 +423,7 @@ trigger_project_b:
     strategy: depend
     include:
       - local: "apps/project-bar/.gitlab-ci.yml"
-          
+
 callback:
   stage: callback
   script: