Setting up Automatic Deployment from one repository to another

Tousif Izaz — Thu, 09 Oct 2025 02:57:12 +0000

I recently wanted to host my React portfolio on GitHub Pages, but with a twist. Most tutorials show you how to deploy to [username.github.io/repository-name], which is straightforward. However, I wanted my portfolio to live at the root domain: username.github.io.
But, I didn't want my GitHub Pages repository cluttered with React source code, node_modules, and development files. I wanted clean separation:

One repository for my React source code (development, version control, collaboration)
Another repository (username.github.io) with only the production build

Manually building and pushing every time I made changes? Not ideal. There had to be a better way.

Cross-Repository GitHub Actions

After some tinkering, I discovered GitHub Actions could automate deployments between repositories. Here's what I learned.

Understanding GitHub Pages Root Domain Deployment

Option A: Put React code in username.github.io
❌ Messy: Source code mixed with builds
❌ Unprofessional: Shows development artifacts

Option B: Build locally, push to username.github.io
❌ Manual process every deployment
❌ Error-prone: Forget to build? Push wrong files?
❌ Not scalable: No CI/CD pipeline

Option C: Separate repos + GitHub Actions
✅ Clean separation of concerns
✅ Automated builds and deployments
✅ Professional CI/CD workflow

The Solution: Two-Repository Architecture

Repository 1: my-portfolio (Private/Public)

React source code
Development dependencies
GitHub Actions workflow
Version control for features

Repository 2: username.github.io (Public)

Only production build files
Automatically updated by CI/CD
Serves the live website

Step 1: Setting Up the Workflow File

In my React repository, I created .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main  # Triggers on every push to main
  workflow_dispatch:  # Allows manual deployment

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test -- --watchAll=false --passWithNoTests
        continue-on-error: false

      - name: Build React app
        run: npm run build
        env:
          CI: true

      - name: Verify build output
        run: |
          echo "Build completed successfully"
          ls -la ./build
          du -sh ./build

      - name: Deploy to GitHub Pages repository
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PAGES_DEPLOY_TOKEN }}
          external_repository: username/username.github.io
          publish_branch: main #branch name of repo u want to deploy to
          publish_dir: ./build #directory of the action
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'
          commit_message: 'Deploy from ${{ github.repository }}@${{ github.sha }}'

Step 2: Authentication Setup

GitHub Actions needs permission to push to another repository. Here's what I learned about authentication options:

Option A: Personal Access Token (What I Used)

Creating the token:

GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Generate new token (classic)
Name it descriptively: "Portfolio Deploy to GitHub Pages"
Expiration: Choose based on security needs
Required scopes:

repo - Full control of repositories
workflow - Update GitHub Action workflows

Adding to repository secrets:

Go to React repository → Settings → Secrets and variables → Actions
New repository secret
Name: PAGES_DEPLOY_TOKEN
Value: Paste the token
Add secret

Option B: Deploy Keys (More Secure Alternative)

I also explored deploy keys, which are SSH-based and repository-specific:

# Generate SSH key pair
ssh-keygen -t ed25519 -C "deploy-key-pages" -f deploy_key -N ""

Then:

Add deploy_key.pub to username.github.io → Settings → Deploy keys (with write access)
Add deploy_key (private) to React repo → Settings → Secrets as PAGES_DEPLOY_KEY

Update workflow to use deploy_key: ${{ secrets.PAGES_DEPLOY_KEY }} instead of personal_token.

Why I chose Personal Access Token:

Simpler for a single-user portfolio. Deploy keys are better for team projects.

Configuring the Build

Important customizations I had to make:

yaml# Node version matching my local environment
node-version: '18'  # Check with: node --version

# Build output directory
publish_dir: ./build  # React uses 'build', Vite uses 'dist'

# Package manager
run: npm ci  # Or 'yarn install --frozen-lockfile' for Yarn

Pro tip: Always verify your build directory locally:

npm run build
ls -la  # Check if 'build' or 'dist' folder was created

Step 4: Testing the Workflow
First deployment:

git add .github/workflows/deploy.yml
git commit -m "Add automated deployment workflow"
git push origin main

Then I monitored it:

React repository → Actions tab
Watched the "Deploy to GitHub Pages" workflow
Each step showed real-time logs
Green checkmarks = success!

Within 5 minutes, username.github.io received the build files and my portfolio was live!

How It Works: The Complete Flow

Developer pushes code
        ↓
GitHub Actions triggers in React repo
        ↓
1. Checkout source code
2. Install dependencies
3. Run tests
4. Build React app (npm run build)
5. Generate ./build folder
        ↓
Workflow authenticates with token
        ↓
Push build files to username.github.io
        ↓
GitHub Pages auto-deploys
        ↓
Site live at username.github.io

Troubleshooting Issues I Encountered

Issue 1: Build Fails in CI but Works Locally

Problem: Different Node versions
Solution: Match Node version in workflow to local:

node --version  # Check local version
# Update workflow: node-version: '18'

Issue 2: 404 on GitHub Pages

Problem: Routing issues with React Router
Solution:

Make sure your homepage for the react is set correctly.
Add 404.html that redirects to index.html or use hash routing: <BrowserRouter basename="/"> // For username.github.io

Resources

GitHub Actions Documentation
peaceiris/actions-gh-pages
GitHub Pages Documentation

DEV Community: Tousif Izaz