docs: NuxtHub github action & app (#390)

Co-authored-by: Sébastien Chopin <[email protected]>
Co-authored-by: Sébastien Chopin <[email protected]>

docs/content/0.index.yml

@@ -10,8 +10,8 @@ hero:
     light: '/images/landing/hero-light.svg'
     dark: '/images/landing/hero-dark.svg'
   headline:
-    label: "Cloudflare Access integration"
-    to: /changelog/cloudflare-access
+    label: "NuxtHub Github App & Action"
+    to: /changelog/github-app-and-action
     icon: i-lucide-arrow-right
 features:
   - name: Cloud Hosting

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

@@ -43,10 +43,6 @@ Toggle between production and preview environments in the NuxtHub admin using th
 
 ## NuxtHub CLI
 
-::important
-If you do your first deployment with the NuxtHub CLI, you won't be able to attach your GitHub/GitLab repository later on due to a Cloudflare limitation, but you can use the [Github action](#github-action) to deploy on commit.
-::
-
 Deploy your local project with a single command:
 
 ```bash [Terminal]
@@ -71,76 +67,178 @@ The command will:
 You can also install the [NuxtHub CLI](https://github.com/nuxt-hub/cli) globally with: `npm i -g nuxthub`.
 ::
 
-### GitHub Action
+## GitHub Action
+
+After linking a GitHub repository to your project, NuxtHub automatically adds a GitHub Actions workflow to automatically deploy your application on every commit using the [NuxtHub GitHub Action](https://github.com/marketplace/actions/deploy-to-nuxthub).
+
+NuxtHub integrates with [GitHub deployments](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments). This allows you to:
+- [View deployment statuses within GitHub](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/viewing-deployment-history)
+- [Setup deployment concurrency](https://docs.github.com/en/actions/use-cases-and-examples/deploying/deploying-with-github-actions#using-concurrency)
+- [Require approvals for deploying to environments](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments)
 
-To deploy your project with a GitHub Action, you can use the following workflow:
+After deploying from a pull request, NuxtHub automatically adds a comment with information about the deployment.
+
+:nuxt-img{src="/images/docs/nuxthub-github-app-pr-comment.png" alt="NuxtHUb GitHub Action commenting on pull requests" width="926" height="520"}
+
+::tip
+You can customise the workflow to tailor to any specific custom DevOps requirements.
+::
 
-```yaml [.github/workflows/deploy.yml]
-name: Deploy with NuxtHub CLI
+::note{to="#linking-a-repository-to-existing-projects"}
+Projects created prior to releasing our GitHub Action uses Pages CI for deployments. Read our [migration guide](#linking-a-repository-to-existing-projects).
+::
+
+### Default workflow
+
+The GitHub Workflow added to your repository is automatically tailored to your project's package manager. This is an example of a workflow added for a project using pnpm.
+
+Currently, the supported package managers
+
+```yaml [.github/workflows/nuxthub.yml]
+name: Deploy to NuxtHub
 on: push
+
 jobs:
-  build-and-deploy:
+  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:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-        name: Install pnpm
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
         with:
-          run_install: false
+          version: 9
+
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
-      - name: Get pnpm store directory
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-      - uses: actions/cache@v4
-        name: Setup pnpm cache
-        with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
+
       - name: Install dependencies
         run: pnpm install
 
-      - name:  Deploy with nuxthub
-        run: npx nuxthub deploy
-        env:
-          NUXT_HUB_PROJECT_KEY: ${{ secrets.NUXT_HUB_PROJECT_KEY}}
-          NUXT_HUB_USER_TOKEN: ${{ secrets.NUXT_HUB_USER_TOKEN }}
+      - name: Build application
+        run: pnpm run build
+
+      - name: Deploy to NuxtHub
+        uses: nuxt-hub/action@v1
+        id: deploy
 ```
 
-You need to add the following secrets to your GitHub repository:
-- `NUXT_HUB_PROJECT_KEY`: Your project key (available in your project settings in the NuxtHub Admin or in your `.env` file if you ran `npx nuxthub link`)
-- `NUXT_HUB_USER_TOKEN`: Your user token available in **User settings** → **Tokens** in the NuxtHub Admin
+### Options
 
-::tip
-We recommend to create a new user token for the Github CI so you can revoke it at any time or add an expiration date.
+#### Inputs
+
+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="project-key" type="string"}
+    The project key of the NuxtHub project to deploy to. If the repository is linked to more than one project, project key is required.
+  ::
 ::
 
+#### Outputs
+
+The GitHub Action provides the following outputs that you can use in subsequent workflow steps.
+
+
+::field-group
+  ::field{name="environment" type="'production' | 'preview'"}
+    The environment of the deployment (e.g. production, preview).
+  ::
+
+  ::field{name="deployment-url" type="string"}
+    The URL of the deployment. For preview environments, it links to the deployment of the commit.
+
+    Examples:
+    - https://example.nuxt.dev (main)
+    - https://abcdefg.example.pages.dev (feat/example)
+  ::
+
+  ::field{name="branch-url" type="string"}
+    The permanent URL for the current branch deployment.
+
+    Examples:
+    - https://example.nuxt.dev (main)
+    - https://feat-example.example.pages.dev (feat/example)
+  ::
+::
+
+### Environment Variables & Secrets
+
+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
+
+In order to use the GitHub Actions secret, you need to update the GitHub Actions workflow to use the secret as environment variable:
+
+```diff [.github/workflows/nuxthub.yml]
+  - name: Build application
+    run: pnpm run build
++   env:
++     NUXT_UI_PRO_LICENSE: ${{ secrets.NUXT_UI_PRO_LICENSE }}
+```
+
 ::note
-This GitHub action uses pnpm to install dependencies. If you are using npm or yarn, we recommend you to adapt the action to your needs.
+This is mostly useful for build-time environment variables.
 ::
 
-## Cloudflare Pages CI
+### Setup
+
+#### Creating a new project
+
+When creating a new project from a template, or importing a Git repository, the GitHub Action workflow will automatically be set up for you.
+
+#### Linking a repository to existing projects
+
+Link your project to a GitHub repository within [NuxtHub Admin](https://admin.hub.nuxt.com/) → Project → Settings → Git.
 
 ::warning
-You should never create the project on Cloudflare Pages as NuxtHub will create it for you.
+Only non-secret environment variables are automatically copied to GitHub. Existing environment secrets are not automatically migrated to GitHub, and should be updated to sync them to GitHub.
 ::
 
-It is possible to use [Cloudflare Pages CI](https://pages.cloudflare.com) to deploy your project by connecting your GitHub or GitLab account. Once your repository is connected, each commit will trigger a new deployment.
+#### Monorepo setup
 
-1. Open the [NuxtHub Admin](https://admin.hub.nuxt.com)
-2. Click on `New Project` then `Import a GitHub repository`
-3. Select your Github repository
-4. Click on `Import repository`
+Our GitHub integration supports deploying multiple applications from the same repository.
 
-::tip
-That's it! NuxtHub will automatically configure the necessary resources and environment variables for you start a deployment on Cloudflare.
+When linking a Git repository, set "project root directory" to the base folder of your Nuxt application corresponding to that NuxtHub project.
+
+When a repository is already linked to at least one project, additional projects linked will have the generated GitHub Actions workflow named `nuxthub-<projectSlug>.yml`.
+
+::note
+When multiple projects are linked to the same repository, the [`project-key`](#inputs) input parameter must be specified on each [Deploy to NuxtHub GitHub Action](https://github.com/marketplace/actions/deploy-to-nuxthub).
+::
+
+**Current limitations**
+
+- Separate applications should be deployed using different workflow jobs.
+
+## Cloudflare Pages CI
+
+Importing an existing Cloudflare Pages project that is already linked to a Git repository will use [Cloudflare Pages CI](https://pages.cloudflare.com) to deploy your project.
+
+- Each commit will trigger a new deployment within Pages CI.
+- Environment variables set within NuxtHub Admin will be available during CI.
+
+::note
+All existing projects with a Git repository linked to Cloudflare Pages prior to our GitHub Action being released uses [Cloudflare Pages CI](https://pages.cloudflare.com) for automated deployments.
+::
+
+::tip{to="#migrating-to-from-pages-ci"}
+You can migrate from Cloudflare Pages CI to [GitHub Actions](#github-action) at any time. Read our [migration guide](#linking-a-repository-to-existing-projects).
 ::
 
 ## Self-hosted

docs/content/4.changelog/github-app-and-action.md

@@ -0,0 +1,68 @@
+---
+title: NuxtHub GitHub App & Action
+description: "Introducing our GitHub App & Action for automating your Nuxt deployments with GitHub as well as a new project creation flow."
+date: 2024-12-23
+image: '/images/changelog/nuxthub-github-app-action.png'
+authors:
+  - name: Rihan Arfan
+    avatar:
+      src: https://avatars.githubusercontent.com/u/20425781?v=4
+    to: https://bsky.app/profile/rihan.dev
+    username: RihanArfan
+  - name: Sebastien Chopin
+    avatar: 
+      src: https://avatars.githubusercontent.com/u/904724?v=4
+    to: https://bsky.app/profile/atinux.com
+    username: atinux
+---
+
+We're thrilled to release our brand new [GitHub Application](https://github.com/apps/nuxthub-admin) & [GitHub Action](https://github.com/marketplace/actions/deploy-to-nuxthub) to help you create and deploy Nuxt applications to NuxtHub.
+
+
+## Pull Request Integration
+
+Once setup, NuxtHub will automatically comment on pull requests with branch URLs, permalinks and QR codes for easy preview access.
+
+:nuxt-img{src="/images/changelog/nuxthub-github-app-action.png" alt="GitHub Action" width="926" height="520"}
+
+## GitHub Deployments
+
+NuxtHub also integrates with GitHub's deployment system, including status updates and environment tracking.
+
+:nuxt-img{src="/images/changelog/nuxthub-github-action-deployment.png" alt="NuxtHub GitHub Action deployments" width="926" height="521"}
+
+This includes GitHub Deployments support in pull requests.
+
+:nuxt-img{src="/images/changelog/nuxthub-github-action-deployment-pr.png" alt="NuxtHub GitHub Action deployments" width="926" height="219"}
+
+And many more:
+- **Deployment Protection**: Support for GitHub's deployment protection rules which enable approval workflows and environment restrictions ([learn more on GitHub's documentation](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#deployment-protection-rules))
+- **Secure**: Our GitHub integration prevents the need for long-lived secrets as it uses OIDC under the hood
+- **Customizable**: You can create tailored workflows to fit your DevOps requirements using our GitHub Action
+
+## Cloning a Template
+
+Thanks to the new GitHub App, you can now clone a template from NuxtHub Admin and deploy it with a single click.
+
+:nuxt-img{src="/images/changelog/nuxthub-github-app-clone-template.png" alt="NuxtHub GitHub App clone template" width="2596" height="1460"}
+
+::note
+The repository will be created in your GitHub account with the GitHub Actions workflow already configured.
+::
+
+## Migrating to GitHub Actions
+
+Migrating from Cloudflare Pages CI or the legacy GitHub Action is simple and can be done from [NuxtHub Admin](https://admin.hub.nuxt.com/) → Project → Settings → Git.
+
+<!-- img of migration alert -->
+
+When migrating from Cloudflare Pages CI, please note:
+
+- Deployment quotas will shift from [Pages CI limits](https://developers.cloudflare.com/pages/platform/limits/#builds) to your [GitHub Actions usage](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions#included-storage-and-minutes)
+- Environment variables and secrets needed at build time should be managed through [GitHub Environment settings](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-an-environment) (we are working on a way to synchronize them automatically)
+
+::callout{to="/docs/getting-started/deploy#github-action" icon="i-lucide-book"}
+Learn more about deploying with GitHub Actions to NuxtHub.
+::
+
+P.S. Give our new [GitHub Action](https://github.com/nuxt-hub/action) a star 🌟💚