Skip to content

Commit f4bae95

Browse files
Emily-JiangEmily-Jiang
authored
Create build-and-deploy-tutorial.yml
1 parent f4a216e commit f4bae95

File tree

1 file changed

+255
-0
lines changed

1 file changed

+255
-0
lines changed

‎.github/workflows/build-and-deploy-tutorial.yml‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# GitHub Actions workflow for building and deploying MicroProfile Tutorial documentation
2+
# This workflow uses Antora to generate a static documentation site from AsciiDoc sources
3+
# and deploys it to GitHub Pages
4+
name: Generate MicroProfile Tutorial
5+
6+
on:
7+
# Allows manual triggering of the workflow from the GitHub Actions tab
8+
workflow_dispatch:
9+
10+
# Automatically runs when code is pushed to the main branch
11+
push:
12+
branches:
13+
- main
14+
15+
# Runs on pull requests to validate the build (but doesn't deploy)
16+
pull_request:
17+
branches:
18+
- main
19+
20+
# Prevent concurrent deployments to avoid conflicts and race conditions
21+
# Only allow one deployment at a time, but don't cancel in-progress runs
22+
# as we want to allow production deployments to complete
23+
concurrency:
24+
group: "pages"
25+
cancel-in-progress: false
26+
27+
jobs:
28+
# Validation job for pull requests - builds but doesn't deploy
29+
validate-build:
30+
# Only run this job on pull requests
31+
if: github.event_name == 'pull_request'
32+
33+
runs-on: ubuntu-latest
34+
35+
# Minimal permissions needed for PR validation
36+
permissions:
37+
contents: read # Required to read repository contents
38+
39+
steps:
40+
# Checkout the repository source code
41+
- name: Checkout Repository
42+
uses: actions/checkout@v4
43+
44+
# Set up Node.js runtime environment for Antora
45+
- name: Set up Node.js
46+
uses: actions/setup-node@v4
47+
with:
48+
node-version: '20' # LTS version compatible with Antora
49+
cache: 'npm' # Cache npm dependencies for faster builds
50+
51+
# Set up Ruby for AsciiDoc extensions
52+
- name: Set up Ruby
53+
uses: ruby/setup-ruby@v1
54+
with:
55+
ruby-version: '3.2'
56+
bundler-cache: false
57+
58+
# Install Antora CLI, site generator, and advanced extensions
59+
- name: Install Antora and Extensions
60+
run: |
61+
npm install @antora/cli @antora/site-generator-default
62+
npm install @antora/lunr-extension @antora/pdf-extension @asciidoctor/tabs
63+
gem install asciidoctor-pdf asciidoctor-kroki asciidoctor-plantuml
64+
65+
# Generate the documentation site to validate it builds correctly
66+
- name: Validate Site Generation
67+
run: npx antora --fetch --stacktrace antora-assembler.yml
68+
69+
# Verify the build output exists
70+
- name: Verify Build Output
71+
run: |
72+
if [ -d "./build/site" ]; then
73+
echo "✅ Site generated successfully"
74+
ls -la ./build/site
75+
# Check if PDF was generated (it's actually generated as index.pdf in _exports)
76+
echo "🔍 Looking for generated PDF files..."
77+
find . -name "*.pdf" -type f
78+
79+
if [ -f "./build/assembler/microprofile-tutorial/6.1/_exports/index.pdf" ] || [ -f "./build/site/microprofile-tutorial/6.1/_exports/index.pdf" ]; then
80+
echo "✅ PDF generated successfully (found as index.pdf in _exports)"
81+
else
82+
echo "⚠️ PDF not generated in expected location"
83+
find . -name "*.pdf" -type f
84+
fi
85+
else
86+
echo "❌ Site generation failed - output directory not found"
87+
exit 1
88+
fi
89+
# Main job that builds the Antora documentation and deploys to GitHub Pages
90+
build-and-deploy:
91+
# Only deploy to Pages on pushes to main branch, not on PRs
92+
# This prevents deploying from pull request builds
93+
if: github.event_name != 'pull_request'
94+
95+
# Use GitHub Pages environment for deployment tracking and protection
96+
environment:
97+
name: github-pages
98+
url: ${{ steps.deployment.outputs.page_url }}
99+
100+
runs-on: ubuntu-latest
101+
102+
# GitHub token permissions required for this workflow
103+
permissions:
104+
id-token: write # Required for OIDC authentication to GitHub Pages
105+
contents: read # Required to read repository contents and checkout code
106+
pages: write # Required to deploy artifacts to GitHub Pages
107+
108+
steps:
109+
# Checkout the repository source code
110+
- name: Checkout Repository
111+
uses: actions/checkout@v4
112+
113+
# Set up Node.js runtime environment for Antora
114+
- name: Set up Node.js
115+
uses: actions/setup-node@v4
116+
with:
117+
node-version: '20' # LTS version compatible with Antora
118+
cache: 'npm' # Cache npm dependencies for faster builds
119+
120+
# Set up Ruby for AsciiDoc extensions
121+
- name: Set up Ruby
122+
uses: ruby/setup-ruby@v1
123+
with:
124+
ruby-version: '3.2'
125+
bundler-cache: false
126+
127+
# Install Antora CLI, site generator, and advanced extensions
128+
- name: Install Antora and Extensions
129+
run: |
130+
npm install @antora/cli @antora/site-generator-default
131+
npm install @antora/lunr-extension @antora/pdf-extension @asciidoctor/tabs
132+
gem install asciidoctor-pdf asciidoctor-kroki asciidoctor-plantuml
133+
134+
# Verify that Antora was installed correctly (useful for debugging)
135+
- name: Verify Antora Installation
136+
run: npm list @antora/cli @antora/site-generator-default || echo "Antora packages are not installed."
137+
138+
# Clean previous build directory to ensure fresh generation
139+
- name: Clean previous build directory
140+
run: |
141+
if [ -d "./build" ]; then
142+
rm -rf ./build
143+
echo "✅ Previous build directory cleaned for fresh generation"
144+
else
145+
echo "ℹ️ No previous build directory found"
146+
fi
147+
148+
# Generate the documentation site using Antora playbook configuration
149+
# --fetch: Downloads remote content sources defined in playbook
150+
# --stacktrace: Shows detailed error information for troubleshooting
151+
- name: Generate Site with Antora
152+
run: npx antora --fetch --stacktrace antora-assembler.yml
153+
154+
# Ensure GitHub Pages is enabled and configure deployment settings
155+
# This will enable Pages if it's not already enabled and set the source to GitHub Actions
156+
- name: Setup Pages
157+
uses: actions/configure-pages@v5
158+
with:
159+
# Automatically enable Pages if not already enabled
160+
enablement: true
161+
# Set the publishing source to GitHub Actions (vs. legacy branch-based)
162+
# This ensures the repository is configured to accept deployments from Actions
163+
token: ${{ secrets.GITHUB_TOKEN }}
164+
165+
# Verify Pages configuration and provide helpful debugging info
166+
- name: Verify Pages Configuration
167+
run: |
168+
echo "🔧 GitHub Pages Configuration Check:"
169+
echo "Repository: ${{ github.repository }}"
170+
echo "Branch: ${{ github.ref_name }}"
171+
echo "Event: ${{ github.event_name }}"
172+
echo "Actor: ${{ github.actor }}"
173+
echo ""
174+
echo "✅ Pages setup completed successfully"
175+
echo "📄 Site will be deployed from ./build/site directory"
176+
# Verify PDF generation and copy to correct location for download
177+
- name: Verify PDF generation and copy to correct location for download
178+
run: |
179+
echo "🔍 Looking for generated PDF files..."
180+
find . -name "*.pdf" -type f
181+
182+
# The PDF is actually generated as index.pdf in _exports subdirectory
183+
PDF_SOURCE=""
184+
if [ -f "./build/assembler/microprofile-tutorial/6.1/_exports/index.pdf" ]; then
185+
PDF_SOURCE="./build/assembler/microprofile-tutorial/6.1/_exports/index.pdf"
186+
echo "✅ PDF found in assembler/_exports location"
187+
elif [ -f "./build/site/microprofile-tutorial/6.1/_exports/index.pdf" ]; then
188+
PDF_SOURCE="./build/site/microprofile-tutorial/6.1/_exports/index.pdf"
189+
echo "✅ PDF found in site/_exports location"
190+
else
191+
echo "❌ PDF not found in expected locations"
192+
echo "Available PDF files:"
193+
find . -name "*.pdf" -type f
194+
exit 1
195+
fi
196+
197+
if [ -n "$PDF_SOURCE" ]; then
198+
PDF_SIZE=$(stat -f%z "$PDF_SOURCE" 2>/dev/null || stat -c%s "$PDF_SOURCE")
199+
echo "PDF Size: ${PDF_SIZE} bytes"
200+
201+
# Copy PDF to the exact location the download link expects
202+
# The download link is ../../microprofile-tutorial/6.1/microprofile-tutorial.pdf
203+
# From /microprofile-tutorial/6.1/index.html, this resolves to /microprofile-tutorial/6.1/microprofile-tutorial.pdf
204+
mkdir -p "./build/site/microprofile-tutorial/6.1/"
205+
cp "$PDF_SOURCE" "./build/site/microprofile-tutorial/6.1/microprofile-tutorial.pdf"
206+
echo "✅ PDF copied to download location: /microprofile-tutorial/6.1/microprofile-tutorial.pdf"
207+
208+
# Verify the copy was successful
209+
if [ -f "./build/site/microprofile-tutorial/6.1/microprofile-tutorial.pdf" ]; then
210+
echo "✅ PDF verification successful"
211+
ls -la ./build/site/microprofile-tutorial/6.1/microprofile-tutorial.pdf
212+
else
213+
echo "❌ PDF copy failed"
214+
exit 1
215+
fi
216+
217+
# Create .htaccess for GitHub Pages to ensure proper PDF serving
218+
cat > ./build/site/.htaccess << 'EOF'
219+
# Set proper MIME type for PDF files
220+
<Files "*.pdf">
221+
AddType application/pdf .pdf
222+
Header set Content-Type "application/pdf"
223+
Header set Content-Disposition "attachment; filename=\"microprofile-tutorial.pdf\""
224+
Header set Cache-Control "no-cache, no-store, must-revalidate"
225+
Header set Pragma "no-cache"
226+
Header set Expires "0"
227+
</Files>
228+
EOF
229+
230+
# Also create PDF-specific .htaccess in the PDF directory
231+
cp supplemental-ui/pdf-htaccess "./build/site/microprofile-tutorial/6.1/.htaccess"
232+
echo "✅ PDF-specific .htaccess created"
233+
234+
echo "✅ PDF download headers configured"
235+
fi
236+
# Copy assembler directory to site for PDF access via UI bundle
237+
- name: Copy assembler directory to site for PDF access
238+
run: |
239+
if [ -d "./build/assembler" ]; then
240+
cp -r ./build/assembler ./build/site/
241+
echo "✅ Assembler directory copied to site for web access"
242+
ls -la ./build/site/assembler/microprofile-tutorial/6.1/
243+
else
244+
echo "⚠️ Assembler directory not found"
245+
fi
246+
# Upload the generated Antora site as a GitHub Pages artifact
247+
- name: Upload Antora Site to GitHub Pages
248+
uses: actions/upload-pages-artifact@v3
249+
with:
250+
path: ./build/site # Antora's default output directory
251+
252+
# Deploy the uploaded artifact to GitHub Pages
253+
- name: Deploy to GitHub Pages
254+
id: deployment
255+
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)