From 4fcc2b5c40ad377065edcbf948f0fd58a7bea370 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arthur=20F=C3=BCcher?= Date: Mon, 30 Mar 2026 22:42:27 -0300 Subject: [PATCH 1/4] ci: add docs-deploy workflow and deployment guide (#96) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add .github/workflows/docs-deploy.yml: - Triggers on push to main (paths: website/** and project/src/**) - Supports manual trigger via workflow_dispatch - Builds library → copies bundle → builds Astro site → deploys to AstroDraw/astrodraw.github.io via peaceiris/actions-gh-pages - Uses DOCS_DEPLOY_KEY secret for SSH deploy key authentication - Add docs/docs-deploy.md: - Explains what each workflow step does - One-time SSH key pair setup instructions - How to manually trigger via GitHub Actions UI - Debugging guide for common failure scenarios Closes #96 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca --- .github/workflows/docs-deploy.yml | 50 +++++++++++++ docs/docs-deploy.md | 114 ++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 .github/workflows/docs-deploy.yml create mode 100644 docs/docs-deploy.md diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000..66fff64 --- /dev/null +++ b/.github/workflows/docs-deploy.yml @@ -0,0 +1,50 @@ +name: Deploy Docs + +on: + push: + branches: + - main + paths: + - 'website/**' + - 'project/src/**' + workflow_dispatch: + +jobs: + build-and-deploy: + runs-on: ubuntu-22.04 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: Install root dependencies + run: npm ci + + - name: Build library + run: npm run build + + - name: Copy bundle to website + run: cp dist/astrochart.js website/public/astrochart.js + + - name: Install website dependencies + run: npm ci + working-directory: website + + - name: Build Astro site + run: npm run build + working-directory: website + + - name: Deploy to astrodraw.github.io + uses: peaceiris/actions-gh-pages@v3 + with: + deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }} + external_repository: AstroDraw/astrodraw.github.io + publish_branch: main + publish_dir: website/dist + user_name: 'github-actions[bot]' + user_email: 'github-actions[bot]@users.noreply.github.com' + commit_message: 'docs: deploy from AstroChart@${{ github.sha }}' diff --git a/docs/docs-deploy.md b/docs/docs-deploy.md new file mode 100644 index 0000000..421291a --- /dev/null +++ b/docs/docs-deploy.md @@ -0,0 +1,114 @@ +# Docs Deployment Guide + +This document explains how the AstroChart documentation site is built and deployed to [astrodraw.github.io](https://astrodraw.github.io/). + +--- + +## What the Workflow Does + +The workflow file is located at `.github/workflows/docs-deploy.yml`. + +It runs on every push to `main` that touches either `website/**` or `project/src/**`, and can also be triggered manually. + +**Steps (in order):** + +1. **Checkout** — checks out the `AstroChart` repository. +2. **Set up Node.js 20** — installs Node using `actions/setup-node`. +3. **Install root dependencies** — runs `npm ci` at the repo root. +4. **Build library** — runs `npm run build` to produce `dist/astrochart.js` (webpack UMD bundle). +5. **Copy bundle to website** — copies `dist/astrochart.js` → `website/public/astrochart.js` so the live demos can load it. +6. **Install website dependencies** — runs `npm ci` inside `website/`. +7. **Build Astro site** — runs `npm run build` inside `website/`, outputting the static site to `website/dist/`. +8. **Deploy to astrodraw.github.io** — uses [`peaceiris/actions-gh-pages@v3`](https://github.com/peaceiris/actions-gh-pages) to push `website/dist/` to the `main` branch of `AstroDraw/astrodraw.github.io` via SSH deploy key. + +The resulting site is served at **https://astrodraw.github.io/**. + +--- + +## One-Time Setup (SSH Deploy Key) + +This is a one-time setup per environment. Once done, the secret persists and no further action is needed. + +### 1. Generate an SSH key pair + +Run this locally (no passphrase): + +```bash +ssh-keygen -t ed25519 -C "docs-deploy" -f docs_deploy_key -N "" +``` + +This creates two files: +- `docs_deploy_key` — **private key** (never share or commit) +- `docs_deploy_key.pub` — **public key** + +### 2. Add the public key as a Deploy Key on astrodraw.github.io + +1. Go to `https://github.com/AstroDraw/astrodraw.github.io/settings/keys` +2. Click **Add deploy key** +3. Title: `AstroChart CI` +4. Key: paste the contents of `docs_deploy_key.pub` +5. Check **Allow write access** +6. Click **Add key** + +### 3. Add the private key as a Secret in AstroChart + +1. Go to `https://github.com/AstroDraw/AstroChart/settings/secrets/actions` +2. Click **New repository secret** +3. Name: `DOCS_DEPLOY_KEY` +4. Value: paste the entire contents of `docs_deploy_key` (including the `-----BEGIN...` and `-----END...` lines) +5. Click **Add secret** + +### 4. Delete the local key files + +```bash +rm docs_deploy_key docs_deploy_key.pub +``` + +> ⚠️ Never commit these files. They are not needed locally after setup. + +--- + +## How to Manually Trigger the Workflow + +You can trigger a deploy at any time without pushing code: + +1. Go to the **Actions** tab in the AstroChart repository: + `https://github.com/AstroDraw/AstroChart/actions/workflows/docs-deploy.yml` +2. Click **Run workflow** +3. Select the branch (typically `main`) +4. Click **Run workflow** + +The workflow will run and deploy the current state of `main` to GitHub Pages. + +--- + +## How to Debug Deploy Failures + +### Step 1 — Check the workflow logs + +Go to `https://github.com/AstroDraw/AstroChart/actions` and click the failed run. Each step's output is expandable. Common failure points: + +| Step | Likely cause | +|---|---| +| Build library | TypeScript compile error or missing dep — run `npm run build` locally | +| Build Astro site | MDX/Astro error — run `cd website && npm run build` locally | +| Deploy to astrodraw.github.io | SSH key problem (see below) | + +### Step 2 — SSH key issues + +If the deploy step fails with an authentication or permission error: + +- **"Permission denied (publickey)"** — the deploy key is wrong or missing. Re-do the one-time setup steps above. +- **"Key is not in correct format"** — the secret was pasted with extra whitespace or is missing the header/footer lines. Delete the secret and re-paste the raw key file content. +- **"Remote: Permission to AstroDraw/astrodraw.github.io denied"** — the deploy key on `astrodraw.github.io` does not have write access. Go to the deploy key settings and verify **Allow write access** is checked. + +### Step 3 — Verify the deployed site + +After a successful run: + +1. Visit `https://astrodraw.github.io/` — homepage should load. +2. Open browser DevTools → Network tab — no 404s for `/astrochart.js`. +3. Click through the sidebar — navigation should work. +4. Open the browser console — no JS errors. + +If the site shows stale content, GitHub Pages may have a CDN cache delay of up to 10 minutes after deployment. From d5a0c568f1803fcea49f7d69bfedcea53c064cb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arthur=20F=C3=BCcher?= Date: Tue, 31 Mar 2026 07:47:22 -0300 Subject: [PATCH 2/4] ci: switch to official GitHub Pages action, deploy from AstroChart repo (#96) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace peaceiris/actions-gh-pages (third-party, slow to maintain, requires SSH deploy key setup) with the official GitHub Actions stack: - actions/upload-pages-artifact@v3 - actions/deploy-pages@v4 Changes: - Split single job into build + deploy jobs - Add top-level permissions (pages: write, id-token: write, contents: read) - Add concurrency group to prevent overlapping deploys - Remove all external repo / SSH deploy key config — no secrets needed - Site now deploys directly to AstroChart repo Pages Update website/astro.config.mjs: - site: https://astrodraw.github.io/AstroChart - base: /AstroChart (required for project repo sub-path deployment) Update docs/docs-deploy.md to reflect new one-time setup (Pages source → GitHub Actions in repo settings) and remove SSH key instructions. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca --- .github/workflows/docs-deploy.yml | 34 ++++++++---- docs/docs-deploy.md | 90 +++++++++++++++---------------- website/astro.config.mjs | 3 +- 3 files changed, 68 insertions(+), 59 deletions(-) diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index 66fff64..bcec0f0 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -9,8 +9,17 @@ on: - 'project/src/**' workflow_dispatch: +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + jobs: - build-and-deploy: + build: runs-on: ubuntu-22.04 steps: - name: Checkout @@ -38,13 +47,18 @@ jobs: run: npm run build working-directory: website - - name: Deploy to astrodraw.github.io - uses: peaceiris/actions-gh-pages@v3 + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 with: - deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }} - external_repository: AstroDraw/astrodraw.github.io - publish_branch: main - publish_dir: website/dist - user_name: 'github-actions[bot]' - user_email: 'github-actions[bot]@users.noreply.github.com' - commit_message: 'docs: deploy from AstroChart@${{ github.sha }}' + path: website/dist + + deploy: + needs: build + runs-on: ubuntu-22.04 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/docs-deploy.md b/docs/docs-deploy.md index 421291a..af9f661 100644 --- a/docs/docs-deploy.md +++ b/docs/docs-deploy.md @@ -1,6 +1,8 @@ # Docs Deployment Guide -This document explains how the AstroChart documentation site is built and deployed to [astrodraw.github.io](https://astrodraw.github.io/). +This document explains how the AstroChart documentation site is built and deployed to GitHub Pages directly from this repository. + +The live site is served at **https://astrodraw.github.io/AstroChart/**. --- @@ -10,7 +12,9 @@ The workflow file is located at `.github/workflows/docs-deploy.yml`. It runs on every push to `main` that touches either `website/**` or `project/src/**`, and can also be triggered manually. -**Steps (in order):** +The workflow has two jobs: + +### Job 1: `build` 1. **Checkout** — checks out the `AstroChart` repository. 2. **Set up Node.js 20** — installs Node using `actions/setup-node`. @@ -19,52 +23,26 @@ It runs on every push to `main` that touches either `website/**` or `project/src 5. **Copy bundle to website** — copies `dist/astrochart.js` → `website/public/astrochart.js` so the live demos can load it. 6. **Install website dependencies** — runs `npm ci` inside `website/`. 7. **Build Astro site** — runs `npm run build` inside `website/`, outputting the static site to `website/dist/`. -8. **Deploy to astrodraw.github.io** — uses [`peaceiris/actions-gh-pages@v3`](https://github.com/peaceiris/actions-gh-pages) to push `website/dist/` to the `main` branch of `AstroDraw/astrodraw.github.io` via SSH deploy key. - -The resulting site is served at **https://astrodraw.github.io/**. - ---- - -## One-Time Setup (SSH Deploy Key) - -This is a one-time setup per environment. Once done, the secret persists and no further action is needed. - -### 1. Generate an SSH key pair - -Run this locally (no passphrase): - -```bash -ssh-keygen -t ed25519 -C "docs-deploy" -f docs_deploy_key -N "" -``` +8. **Upload Pages artifact** — uploads `website/dist/` as a GitHub Pages artifact using the official `actions/upload-pages-artifact` action. -This creates two files: -- `docs_deploy_key` — **private key** (never share or commit) -- `docs_deploy_key.pub` — **public key** +### Job 2: `deploy` -### 2. Add the public key as a Deploy Key on astrodraw.github.io +1. **Deploy to GitHub Pages** — deploys the uploaded artifact using the official `actions/deploy-pages` action. Uses GitHub's OIDC token — no secrets or SSH keys needed. -1. Go to `https://github.com/AstroDraw/astrodraw.github.io/settings/keys` -2. Click **Add deploy key** -3. Title: `AstroChart CI` -4. Key: paste the contents of `docs_deploy_key.pub` -5. Check **Allow write access** -6. Click **Add key** +--- -### 3. Add the private key as a Secret in AstroChart +## One-Time Setup (GitHub Pages source) -1. Go to `https://github.com/AstroDraw/AstroChart/settings/secrets/actions` -2. Click **New repository secret** -3. Name: `DOCS_DEPLOY_KEY` -4. Value: paste the entire contents of `docs_deploy_key` (including the `-----BEGIN...` and `-----END...` lines) -5. Click **Add secret** +This only needs to be done once per repository. -### 4. Delete the local key files +1. Go to the repository **Settings → Pages**: + `https://github.com/AstroDraw/AstroChart/settings/pages` +2. Under **Source**, select **GitHub Actions** (not a branch). +3. Click **Save**. -```bash -rm docs_deploy_key docs_deploy_key.pub -``` +That's it. The workflow handles everything else automatically. -> ⚠️ Never commit these files. They are not needed locally after setup. +> **Note:** GitHub automatically creates a `github-pages` environment on the first successful deploy. You can see it under **Settings → Environments**. --- @@ -92,23 +70,39 @@ Go to `https://github.com/AstroDraw/AstroChart/actions` and click the failed run |---|---| | Build library | TypeScript compile error or missing dep — run `npm run build` locally | | Build Astro site | MDX/Astro error — run `cd website && npm run build` locally | -| Deploy to astrodraw.github.io | SSH key problem (see below) | +| Upload Pages artifact | `website/dist/` is empty or missing — check the Astro build step above it | +| Deploy to GitHub Pages | Pages source not set to "GitHub Actions" — see one-time setup above | -### Step 2 — SSH key issues +### Step 2 — Permissions error on deploy -If the deploy step fails with an authentication or permission error: +If the deploy job fails with a permissions error: -- **"Permission denied (publickey)"** — the deploy key is wrong or missing. Re-do the one-time setup steps above. -- **"Key is not in correct format"** — the secret was pasted with extra whitespace or is missing the header/footer lines. Delete the secret and re-paste the raw key file content. -- **"Remote: Permission to AstroDraw/astrodraw.github.io denied"** — the deploy key on `astrodraw.github.io` does not have write access. Go to the deploy key settings and verify **Allow write access** is checked. +- Verify the repository **Settings → Pages → Source** is set to **GitHub Actions**, not a branch. +- Verify the workflow has the correct top-level permissions (`pages: write`, `id-token: write`). +- Check that the `deploy` job declares `environment: name: github-pages`. ### Step 3 — Verify the deployed site After a successful run: -1. Visit `https://astrodraw.github.io/` — homepage should load. -2. Open browser DevTools → Network tab — no 404s for `/astrochart.js`. +1. Visit `https://astrodraw.github.io/AstroChart/` — homepage should load. +2. Open browser DevTools → Network tab — no 404s for `/AstroChart/astrochart.js`. 3. Click through the sidebar — navigation should work. 4. Open the browser console — no JS errors. If the site shows stale content, GitHub Pages may have a CDN cache delay of up to 10 minutes after deployment. + +--- + +## Astro base path configuration + +The `website/astro.config.mjs` file is configured with: + +```js +site: 'https://astrodraw.github.io/AstroChart', +base: '/AstroChart', +``` + +The `base` option tells Astro to prefix all internal links and asset URLs with `/AstroChart`, which is required for a project repository deployed to a sub-path. + +If the site is ever moved to the root URL (`https://astrodraw.github.io/`), remove the `base` option and update `site` accordingly. diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 77eca5b..844c018 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -3,7 +3,8 @@ import starlight from '@astrojs/starlight' import sitemap from '@astrojs/sitemap' export default defineConfig({ - site: 'https://astrodraw.github.io/', + site: 'https://astrodraw.github.io/AstroChart', + base: '/AstroChart', integrations: [ starlight({ title: 'AstroChart', From ab5755b7a55664480921064e26090489cf9febbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arthur=20F=C3=BCcher?= Date: Tue, 31 Mar 2026 09:06:10 -0300 Subject: [PATCH 3/4] ci: temporarily enable workflow trigger on issue-96-ci-cd for testing --- .github/workflows/docs-deploy.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index bcec0f0..5db8d97 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -4,6 +4,7 @@ on: push: branches: - main + - issue-96-ci-cd # temporary: remove before merging paths: - 'website/**' - 'project/src/**' From 510c17360a52cfd9d2ed826d8f18df9522b05bca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arthur=20F=C3=BCcher?= Date: Tue, 31 Mar 2026 09:08:58 -0300 Subject: [PATCH 4/4] ci: revert temporary test trigger on issue-96-ci-cd --- .github/workflows/docs-deploy.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index 5db8d97..bcec0f0 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -4,7 +4,6 @@ on: push: branches: - main - - issue-96-ci-cd # temporary: remove before merging paths: - 'website/**' - 'project/src/**'