わたしの部屋

Required Tools#

1
# Verify tools are available
2
git --version
3
gh --version
4
pnpm --version  # or npm/node

If gh is missing, install via scoop (preferred per user rules):

1
scoop install gh

Required Information from User#

Before starting, ask the user for:

1. GitHub Personal Access Token (scopes: repo, workflow, admin:repo_hook)
2. Custom domain (e.g., blog.example.com) — must already have DNS configured
3. Repository strategy: Fork existing template or create new repo
4. Proxy address if behind a firewall (default: http://127.0.0.1:7890)

DNS Prerequisites#

The custom domain must have DNS records pointing to GitHub Pages BEFORE deployment:

Option A — CNAME Record (recommended for subdomains):

1
Type:  CNAME
2
Name:  blog
3
Value: username.github.io

Option B — A Records (for apex domains):

1
Type:  A
2
Name:  @
3
Value: 185.199.108.153
4
Value: 185.199.109.153
5
Value: 185.199.110.153
6
Value: 185.199.111.153

Verify DNS propagation before proceeding:

1
Resolve-DnsName blog.example.com

Set Environment Variables#

1
# Set token and proxy for all subsequent commands
2
$env:GH_TOKEN = "ghp_YOUR_TOKEN_HERE"
3
$env:HTTP_PROXY = "http://127.0.0.1:7890"
4
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

Authenticate with gh CLI#

1
# Login using token (recommended for automation)
2
$env:GH_TOKEN | gh auth login --with-token
3

4
# Verify authentication
5
gh auth status

Common Auth Issues#

Issue: Missing read:org scope

1
! Missing required token scopes: 'read:org'

Fix: Use GH_TOKEN environment variable instead of keyring storage. All gh commands will use the token directly.

Issue: Network timeout connecting to GitHub Fix: Set HTTP_PROXY and HTTPS_PROXY environment variables. Verify connectivity:

1
Test-NetConnection -ComputerName api.github.com -Port 443

Issue: Keyring token invalid

1
X Failed to log in to github.com account (keyring)

Fix: This is expected when using GH_TOKEN env var. The keyring account can be ignored as long as the GH_TOKEN account shows as active.

Configure Git Credential Helper#

1
gh auth setup-git

Option A: Fork Existing Template (Recommended)#

Use this when deploying a template-based project (e.g., Mizuki) while keeping upstream sync capability.

1
# Fork the template repository
2
gh repo fork owner/template-repo --clone=no
3

4
# If already cloned locally, set up remotes
5
cd project-directory
6
git remote add origin https://github.com/YOUR_USERNAME/repo-name.git
7
git remote add upstream https://github.com/original-owner/repo-name.git
8

9
# Verify remotes
10
git remote -v

Option B: Create New Repository#

1
cd project-directory
2
gh repo create repo-name --public --description "Site description" --source . --push

Verify Repository State#

1
# Check git status is clean
2
git status --short
3

4
# Check local and remote are in sync
5
git log --oneline -3
6
git rev-list origin/master..master --count  # Should be 0

Update Site URL#

Locate the site configuration file and update the URL to the custom domain.

For Mizuki-style projects (src/config/siteConfig.ts):

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  siteURL: "https://blog.example.com/",  // Must end with slash
4
  // ...
5
};

For standard Astro projects (astro.config.mjs):

1
export default defineConfig({
2
  site: "https://blog.example.com",
3
  // ...
4
});

Important: Always verify the actual config file path. Some projects use src/config.ts, others use src/config/siteConfig.ts or inline in astro.config.mjs. Check the project structure first.

Create Deployment Workflow#

Create .github/workflows/deploy.yml:

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [master]
6
  workflow_dispatch:
7

8
permissions:
9
  contents: read
10
  pages: write
11
  id-token: write
12

13
concurrency:
14
  group: "pages"
15
  cancel-in-progress: false
16

17
jobs:
18
  build:
19
    runs-on: ubuntu-latest
20
    steps:
21
      - name: Checkout
22
        uses: actions/checkout@v4
23

24
      - name: Setup Node.js
25
        uses: actions/setup-node@v4
26
        with:
27
          node-version: lts/*
28

29
      - name: Setup pnpm
30
        uses: pnpm/action-setup@v4
31
        with:
32
          run_install: false
33

34
      - name: Install dependencies
35
        run: pnpm install --frozen-lockfile
36

37
      - name: Build with Astro
38
        run: pnpm build
39
        env:
40
          ENABLE_CONTENT_SYNC: "false"
41

42
      - name: Setup Pages
43
        uses: actions/configure-pages@v5
44

45
      - name: Upload artifact
46
        uses: actions/upload-pages-artifact@v3
47
        with:
48
          path: dist
49

50
  deploy:
51
    needs: build
52
    runs-on: ubuntu-latest
53
    environment:
54
      name: github-pages
55
      url: ${{ steps.deployment.outputs.page_url }}
56
    steps:
57
      - name: Deploy to GitHub Pages
58
        id: deployment
59
        uses: actions/deploy-pages@v4

Notes on Workflow Configuration#

• Branch name: Change master to main if the default branch is main
• Package manager: If using npm instead of pnpm, replace pnpm steps with npm ci and npm run build
• Content sync: Set ENABLE_CONTENT_SYNC: "false" to disable content separation during CI build
• Build output: Ensure the path matches Astro’s output directory (default: dist)
• Lock file: Ensure pnpm-lock.yaml exists for --frozen-lockfile to work

Commit and Push#

1
git add -A
2
git commit -m "deploy: configure GitHub Pages deployment and custom domain"
3
git push origin master

Configure Pages via API#

1
# Enable GitHub Pages with custom domain
2
gh api repos/YOUR_USERNAME/REPO_NAME/pages `
3
  -X POST `
4
  -f source[branch]=master `
5
  -f source[path]=/ `
6
  -f build_type=workflow `
7
  -f cname=blog.example.com

If Pages Already Exists (Update Instead)#

1
gh api repos/YOUR_USERNAME/REPO_NAME/pages `
2
  -X PUT `
3
  -f build_type=workflow `
4
  -f cname=blog.example.com

Verify Pages Configuration#

1
gh api repos/YOUR_USERNAME/REPO_NAME/pages --jq '{
2
  cname,
3
  build_type,
4
  https_enforced,
5
  status,
6
  url: .html_url,
7
  https_certificate: .https_certificate.state
8
}'

Check Workflow Status#

1
# List workflows
2
gh workflow list --repo YOUR_USERNAME/REPO_NAME
3

4
# List recent runs
5
gh run list --repo YOUR_USERNAME/REPO_NAME --limit 5

Trigger Deployment Manually#

If no run was triggered automatically (e.g., workflow was just added):

1
gh workflow run "Deploy to GitHub Pages" --repo YOUR_USERNAME/REPO_NAME --ref master

Monitor Deployment#

1
# Get the run ID from the previous command output, then:
2
gh run watch <RUN_ID> --repo YOUR_USERNAME/REPO_NAME
3

4
# Or view run details
5
gh run view <RUN_ID> --repo YOUR_USERNAME/REPO_NAME

Common Build Failures#

Issue: pnpm install --frozen-lockfile fails

• Cause: pnpm-lock.yaml is outdated or missing
• Fix: Run pnpm install locally, commit the updated lock file, push again

Issue: Astro build fails with missing dependencies

• Fix: Check package.json scripts, ensure build script exists and outputs to dist

Issue: Node.js 20 deprecation warning

• This is a warning, not an error. The build will still succeed.
• To fix: Update workflow actions to newer versions (e.g., actions/checkout@v5)

Issue: Deploy job fails with “environment not found”

• Fix: The github-pages environment is auto-created on first deployment. Re-run the workflow.

Enable HTTPS Enforcement#

1
# IMPORTANT: Use -F (not -f) for boolean values in gh api
2
gh api repos/YOUR_USERNAME/REPO_NAME/pages -X PUT -F https_enforced=true

Critical: Use -F for boolean values, -f for strings. Using -f true will fail with HTTP 422: "true" is not of type boolean.

Verify HTTPS Configuration#

1
gh api repos/YOUR_USERNAME/REPO_NAME/pages --jq '{
2
  https_enforced,
3
  https_certificate: .https_certificate.state,
4
  https_expires: .https_certificate.expires_at
5
}'

HTTPS certificate provisioning may take a few minutes after the domain is first configured. If the certificate state is pending, wait and check again.

Check Site Accessibility#

1
# Verify DNS resolution
2
Resolve-DnsName blog.example.com
3

4
# Verify HTTP response
5
$response = Invoke-WebRequest -Uri "https://blog.example.com/" -UseBasicParsing -TimeoutSec 30
6
Write-Host "Status: $($response.StatusCode)"
7
Write-Host "Content Length: $($response.Content.Length)"
8

9
# Extract page title
10
if ($response.Content -match '<title[^>]*>([^<]+)</title>') {
11
    Write-Host "Title: $($matches[1])"
12
}

Verify HTTPS Redirect#

1
# HTTP should redirect to HTTPS
2
try {
3
    $response = Invoke-WebRequest -Uri "http://blog.example.com/" -UseBasicParsing -MaximumRedirection 0 -ErrorAction Stop
4
} catch {
5
    # A 301/302 redirect is expected
6
    Write-Host "Redirect status: $($_.Exception.Response.StatusCode)"
7
}

Token Permission Issues#

API Parameter Issues#

Deployment Issues#

Domain Issues#

Local Mode (Default — No Config Needed)#

Content lives in src/content/ and public/images/, committed with the code.

Remote Content Repository#

1
# In .env file:
2
ENABLE_CONTENT_SYNC=true
3
CONTENT_REPO_URL=https://github.com/your-username/Content-Repo.git

For CI/CD deployment, set ENABLE_CONTENT_SYNC=false in the workflow to use local content, or configure secrets for remote sync.

Upstream Sync Strategy#

When using a fork, sync updates from the original template:

1
# Fetch and merge upstream changes
2
git fetch upstream
3
git merge upstream/master
4

5
# Resolve any conflicts in config files, then push
6
git push origin master

Tip: Keep custom content (articles, images, config changes) in separate commits to make conflict resolution easier during upstream syncs.