Skip to content

Commit 7a04cad

Browse files
tyethtyeth
committed
Merge branch 'gh-pages-deploy-tests' into gh-pages-deploy-tests-rebase-main
2 parents 7a85c72 + 69a4892 commit 7a04cad

3 files changed

Lines changed: 294 additions & 0 deletions

File tree

‎.github/workflows/README-deploy-preview.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# GitHub Pages Preview Deployments
2+
3+
This workflow (`deploy-preview.yml`) automatically builds and deploys preview versions of the examples application to GitHub Pages for every branch push and pull request.
4+
5+
## How it works
6+
7+
### Triggering Events
8+
- **Pull Requests**: Triggers on `opened`, `synchronize`, and `reopened` events
9+
- **Branch Pushes**: Triggers on pushes to any branch except `main` (which has its own deployment workflow)
10+
11+
### Deployment Paths
12+
13+
The workflow deploys to the `gh-pages` branch using the following path structure:
14+
15+
- **Pull Requests**: `pr/<pr-number>-<short-sha>/`
16+
- Example: `pr/42-abc1234/`
17+
18+
- **Branches**: `branch/<safe-branch-name>-<short-sha>/`
19+
- Example: `branch/feature_new-ui-a7b8c9d/`
20+
21+
### Base URL Configuration
22+
23+
The workflow automatically:
24+
1. Fetches the GitHub Pages URL using the `gh` CLI
25+
2. Falls back to `https://<owner>.github.io/<repo>` if Pages isn't configured
26+
3. Builds the examples app with the correct base href using Parcel's `--public-url` option
27+
4. All asset paths are absolute URLs pointing to the correct subdirectory
28+
29+
### Features
30+
31+
- ✅ **Automatic PR Comments**: Posts a comment on PRs with the preview URL
32+
- ✅ **Branch Sanitization**: Safely handles branch names with special characters
33+
- ✅ **Incremental Deployments**: Each commit creates a new deployment with a unique SHA
34+
- ✅ **Job Summaries**: Provides deployment URL in GitHub Actions summary
35+
- ✅ **gh-pages Auto-Init**: Creates the gh-pages branch if it doesn't exist
36+
37+
## Usage
38+
39+
### For Pull Requests
40+
1. Open a pull request
41+
2. Wait for the workflow to complete
42+
3. Click the preview URL in the automated comment
43+
4. Each new commit will update the deployment (with a new SHA in the path)
44+
45+
### For Branch Pushes
46+
1. Push commits to any branch (except `main`)
47+
2. Check the workflow run for the deployment URL in the summary
48+
3. Access your preview at: `https://<owner>.github.io/<repo>/branch/<branch-name>-<sha>/`
49+
50+
## Permissions Required
51+
52+
The workflow needs the following permissions:
53+
- `contents: write` - To push to the gh-pages branch
54+
- `pull-requests: write` - To comment on pull requests
55+
- `pages: read` - To fetch the GitHub Pages URL
56+
57+
## Build Process
58+
59+
1. Install root dependencies and build the library
60+
2. Install example app dependencies
61+
3. Clean previous builds
62+
4. Generate API documentation
63+
5. Build example app with Parcel using custom `--public-url`
64+
6. Deploy to gh-pages branch in the appropriate subdirectory
65+
66+
## Customization
67+
68+
### Changing the Deployment Path Format
69+
70+
Edit the "Determine deployment path" step in `.github/workflows/deploy-preview.yml`:
71+
72+
```yaml
73+
- name: Determine deployment path
74+
id: deployment-path
75+
run: |
76+
# Modify DEPLOY_DIR and BASE_HREF variables here
77+
```
78+
79+
### Changing Build Configuration
80+
81+
The build uses Parcel with the following options:
82+
- `--no-optimize`: Faster builds, easier debugging
83+
- `--public-url`: Dynamic base URL for assets
84+
85+
To modify, edit the "Build example with base href" step.
86+
87+
## Troubleshooting
88+
89+
### Preview URL returns 404
90+
- Ensure GitHub Pages is enabled for the repository
91+
- Check that the gh-pages branch exists
92+
- Verify the deployment path in the workflow logs
93+
94+
### Assets not loading
95+
- Check the browser console for failed requests
96+
- Verify the base href is correct in the deployed HTML
97+
- Ensure all asset paths are absolute URLs
98+
99+
### Workflow fails to push
100+
- Check repository permissions
101+
- Verify the `GITHUB_TOKEN` has write access to contents

‎.github/workflows/deploy-preview.yml‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
name: Deploy Preview to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- '**' # All branches
7+
- '!main' # Exclude main branch (handled by pages.yml)
8+
pull_request:
9+
types: [opened, synchronize, reopened]
10+
11+
permissions:
12+
contents: write
13+
pull-requests: write
14+
pages: read
15+
16+
jobs:
17+
deploy-preview:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v4
22+
23+
- name: Set up Node
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: 20
27+
28+
- name: Determine deployment path
29+
id: deployment-path
30+
run: |
31+
# Get the GitHub Pages base URL
32+
GH_PAGES_URL=$(gh api repos/${{ github.repository }}/pages --jq '.html_url' 2>/dev/null || echo "")
33+
34+
if [ -z "$GH_PAGES_URL" ]; then
35+
echo "GitHub Pages not configured, using repository name as base"
36+
REPO_NAME=$(echo "${{ github.repository }}" | cut -d'/' -f2)
37+
GH_PAGES_URL="https://${{ github.repository_owner }}.github.io/${REPO_NAME}"
38+
fi
39+
40+
# Remove trailing slash from base URL
41+
GH_PAGES_URL=${GH_PAGES_URL%/}
42+
43+
# Determine if this is a PR or branch push
44+
if [ "${{ github.event_name }}" = "pull_request" ]; then
45+
PR_NUMBER="${{ github.event.pull_request.number }}"
46+
REF="${{ github.event.pull_request.head.sha }}"
47+
SHORT_REF=${REF:0:7}
48+
DEPLOY_DIR="pr/${PR_NUMBER}-${SHORT_REF}"
49+
BASE_HREF="${GH_PAGES_URL}/pr/${PR_NUMBER}-${SHORT_REF}/"
50+
else
51+
BRANCH_NAME="${{ github.ref_name }}"
52+
# Sanitize branch name for use in paths
53+
SAFE_BRANCH=$(echo "$BRANCH_NAME" | sed 's/[^a-zA-Z0-9-]/_/g')
54+
REF="${{ github.sha }}"
55+
SHORT_REF=${REF:0:7}
56+
DEPLOY_DIR="branch/${SAFE_BRANCH}-${SHORT_REF}"
57+
BASE_HREF="${GH_PAGES_URL}/branch/${SAFE_BRANCH}-${SHORT_REF}/"
58+
fi
59+
60+
echo "deploy_dir=${DEPLOY_DIR}" >> $GITHUB_OUTPUT
61+
echo "base_href=${BASE_HREF}" >> $GITHUB_OUTPUT
62+
echo "gh_pages_url=${GH_PAGES_URL}" >> $GITHUB_OUTPUT
63+
64+
echo "Deployment directory: ${DEPLOY_DIR}"
65+
echo "Base HREF: ${BASE_HREF}"
66+
env:
67+
GH_TOKEN: ${{ github.token }}
68+
69+
- name: Install root dependencies
70+
run: npm install
71+
72+
- name: Build library
73+
run: npm run build
74+
75+
- name: Install example dependencies
76+
run: |
77+
cd examples/typescript
78+
npm install
79+
80+
- name: Build example with base href
81+
run: |
82+
cd examples/typescript
83+
# Clean and generate docs first
84+
npm run clean
85+
npm run genDocs
86+
# Build with the dynamic base href using custom script
87+
npm run parcel:build:custom -- --public-url "${{ steps.deployment-path.outputs.base_href }}"
88+
89+
- name: Checkout gh-pages branch
90+
id: checkout-gh-pages
91+
run: |
92+
# Try to checkout gh-pages branch
93+
if git ls-remote --heads origin gh-pages | grep -q gh-pages; then
94+
echo "gh-pages branch exists"
95+
echo "exists=true" >> $GITHUB_OUTPUT
96+
else
97+
echo "gh-pages branch does not exist"
98+
echo "exists=false" >> $GITHUB_OUTPUT
99+
fi
100+
101+
- name: Setup gh-pages branch
102+
if: steps.checkout-gh-pages.outputs.exists == 'false'
103+
run: |
104+
# Create a temporary directory for gh-pages initialization
105+
TEMP_DIR="${{ runner.temp }}/gh-pages-init"
106+
mkdir -p "$TEMP_DIR"
107+
cd "$TEMP_DIR"
108+
git init
109+
git checkout -b gh-pages
110+
echo "# GitHub Pages - Preview Deployments" > README.md
111+
echo "" >> README.md
112+
echo "This branch contains preview deployments for pull requests and branches." >> README.md
113+
git add README.md
114+
git config user.name "github-actions[bot]"
115+
git config user.email "github-actions[bot]@users.noreply.github.com"
116+
git commit -m "Initialize gh-pages branch"
117+
git remote add origin https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git
118+
git push -u origin gh-pages
119+
120+
- name: Checkout existing gh-pages
121+
if: steps.checkout-gh-pages.outputs.exists == 'true'
122+
uses: actions/checkout@v4
123+
with:
124+
ref: gh-pages
125+
path: gh-pages-repo
126+
127+
- name: Setup deployment directory
128+
run: |
129+
if [ "${{ steps.checkout-gh-pages.outputs.exists }}" = "false" ]; then
130+
# Clone the newly created gh-pages branch
131+
git clone --single-branch --branch gh-pages https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git gh-pages-repo
132+
fi
133+
134+
- name: Deploy to gh-pages
135+
run: |
136+
DEPLOY_DIR="${{ steps.deployment-path.outputs.deploy_dir }}"
137+
138+
# Create deployment directory structure
139+
mkdir -p "gh-pages-repo/${DEPLOY_DIR}"
140+
141+
# Copy built files to deployment directory
142+
cp -r examples/typescript/dist/* "gh-pages-repo/${DEPLOY_DIR}/"
143+
144+
# Configure git
145+
cd gh-pages-repo
146+
git config user.name "github-actions[bot]"
147+
git config user.email "github-actions[bot]@users.noreply.github.com"
148+
149+
# Commit and push
150+
git add .
151+
if git diff --staged --quiet; then
152+
echo "No changes to deploy"
153+
else
154+
git commit -m "Deploy preview: ${{ steps.deployment-path.outputs.deploy_dir }}"
155+
git push origin gh-pages
156+
fi
157+
158+
- name: Comment on PR with preview URL
159+
if: github.event_name == 'pull_request'
160+
uses: actions/github-script@v7
161+
with:
162+
script: |
163+
const deployUrl = '${{ steps.deployment-path.outputs.base_href }}';
164+
const deployDir = '${{ steps.deployment-path.outputs.deploy_dir }}';
165+
const comment = `### 🚀 Preview Deployment Ready!
166+
167+
Your changes have been deployed to GitHub Pages:
168+
169+
**Preview URL:** [${deployUrl}](${deployUrl})
170+
171+
**Deployment Path:** \`${deployDir}\`
172+
173+
This preview will be updated with each new commit to this PR.`;
174+
175+
github.rest.issues.createComment({
176+
owner: context.repo.owner,
177+
repo: context.repo.repo,
178+
issue_number: context.issue.number,
179+
body: comment
180+
});
181+
182+
- name: Output deployment summary
183+
run: |
184+
echo "## Deployment Summary" >> $GITHUB_STEP_SUMMARY
185+
echo "" >> $GITHUB_STEP_SUMMARY
186+
echo "**Deployment URL:** [${{ steps.deployment-path.outputs.base_href }}](${{ steps.deployment-path.outputs.base_href }})" >> $GITHUB_STEP_SUMMARY
187+
echo "" >> $GITHUB_STEP_SUMMARY
188+
echo "**Deployment Directory:** \`${{ steps.deployment-path.outputs.deploy_dir }}\`" >> $GITHUB_STEP_SUMMARY
189+
echo "" >> $GITHUB_STEP_SUMMARY
190+
echo "**Event Type:** ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
191+

‎examples/typescript/package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,14 @@
55
"source": "src/index.html",
66
"scripts": {
77
"build": "npm-run-all clean genDocs parcel:build",
8+
"build:custom-base": "npm-run-all clean genDocs parcel:build:custom",
89
"clean": "shx rm -rf dist .parcel-cache",
910
"dev": "npm-run-all clean genDocs parcel:dev",
1011
"genDocs": "npm run genDocs:root && shx mkdir -p dist && shx cp -r ../../docs dist",
1112
"genDocs:root": "cd ../.. && npm run genDocs",
1213
"parcel:dev": "cross-env PARCEL_WORKERS=0 parcel src/index.html",
1314
"parcel:build": "cross-env PARCEL_WORKERS=0 parcel build src/index.html --no-optimize --public-url ./",
15+
"parcel:build:custom": "cross-env PARCEL_WORKERS=0 parcel build src/index.html --no-optimize",
1416
"test": "echo \"Error: no test specified\" && exit 1"
1517
},
1618
"parcelIgnore": [

0 commit comments

Comments
 (0)