wip: docs

nuxt-hub · Dec 11, 2024 · c7ffd66 · c7ffd66
1 parent 21aa978
commit c7ffd66
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 51 deletions.
diff --git a/docs/content/1.docs/1.getting-started/3.deploy.md b/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,84 @@ 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
+
+- New projects
+- After linking your project to a GitHub repository,
+
+NuxtHub will automatically create a GitHub Actions workflow tailored to your project. The workflow will automatically create a deployment on every commit.
+
+- Full GitHub deployments support, including [deployment protection rules](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#deployment-protection-rules)
+- Pull request comments for branch url, permalink and qr code
+- Workflow fully customisable to fit any DevOps goals
+
+### Setup
+
+- new projec
 
-To deploy your project with a GitHub Action, you can use the following workflow:
+### Migrating to GitHub Actions from Pages CI
 
-```yaml [.github/workflows/deploy.yml]
-name: Deploy with NuxtHub CLI
+If you have more complex deployment requirements, you can customise the GitHub
+
+::note{to="https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#environment-secrets"}
+Environment variables and secrets required for building your Nuxt app should be set within your GitHub environments.
+::
+
+```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 site
+        run: pnpm run build
 
-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
-
-::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.
-::
+      - name: Deploy to NuxtHub
+        uses: nuxt-hub/action@v1
+        id: deploy
+```
 
-::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.
-::
+- If one repo linked, project key doesn't need specifying.
 
 ## Cloudflare Pages CI
 
-::warning
-You should never create the project on Cloudflare Pages as NuxtHub will create it for you.
-::
+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.
 
-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.
+- Each commit will trigger a new deployment within Pages CI.
+- Environment variables set within NuxtHub Admin will be available during CI.
 
-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`
+::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
-That's it! NuxtHub will automatically configure the necessary resources and environment variables for you start a deployment on Cloudflare.
+You can migrate from Cloudflare Pages CI to [GitHub Actions](#github-action) at any time. Begin with process within NuxtHub Admin → Project → Settings → Git.
 ::
 
 ## Self-hosted

diff --git a/docs/content/4.changelog/github-action.md b/docs/content/4.changelog/github-action.md
@@ -0,0 +1,26 @@
+---
+title: GitHub Action
+description: "Tighter GitHub integration and improved automated deployments"
+date: 2024-12-11
+image: '/images/changelog/cloudflare-access.png'
+authors:
+  - name: Rihan Arfan
+    avatar:
+      src: https://avatars.githubusercontent.com/u/20425781?v=4
+    to: https://bsky.app/profile/rihan.dev
+    username: RihanArfan
+---
+
+Summary
+
+:nuxt-img{src="/images/changelog/cloudflare-access.png" alt="GitHub Action" width="915" height="515"}
+
+Explain features (pr comments, gh deployments, deployment approvals)
+
+migration guide + screenshot
+
+caveats (pages ci quota to github actions quota, env variables managed on github)
+
+::callout{to="/docs/getting-started/deploy#github-action" icon="i-lucide-book"}
+Learn more about deploying with GitHub Actions to NuxtHub.
+::