GitHub Integration & Webhooks

​

Overview

• Store your Pageo profile configuration as a JSON file in your GitHub repository
• Version control your profile changes using Git
• Automatically sync updates when you push changes to GitHub
• Manage your profile entirely through code—no UI required

​

Prerequisites

• A GitHub account
• A GitHub repository (public or private)
• A Pageo account
• Your repository must be named exactly as your GitHub username (e.g., if your username is johndoe, your repo should be johndoe/pageo)

​

Step 1: Create Your Repository

1. Go to GitHub and create a new repository
2. Name it exactly as your GitHub username (e.g., if your username is johndoe, name the repo pageo)
3. Make sure the repository is initialized (you can add a README if you want)
4. The default branch should be main

​

Step 2: Create Your pageo.json File

1. In your repository, create a new file called pageo.json in the root directory
2. Add the following structure to the file:

{
  "email": "[email protected]",
  "profile": {
    "name": "Your Name",
    "role": "Your Role",
    "bio": "Your bio here",
    "image": "https://example.com/your-image.jpg",
    "email": "[email protected]"
  },
  "socialLinks": [
    {
      "type": "github",
      "href": "https://github.com/username"
    },
    {
      "type": "x",
      "href": "https://x.com/username"
    }
  ],
  "gridLinks": [
    {
      "title": "My Project",
      "description": "A brief description",
      "image": "https://example.com/project-image.jpg",
      "url": "https://example.com/project",
      "layout": "grid"
    }
  ],
  "settings": {
    "layout": "list",
    "showContactForm": true
  }
}

​

Important Notes:

• The email field must match your Pageo account email
• You don’t need to include order or id fields—Pageo generates these automatically
• socialLinks can have up to 8 items
• gridLinks can have up to 4 items
• The layout setting can be either "list" or "grid"
• showContactForm is optional—only include it if you want to show the contact form

3. Commit and push the file to your repository’s main branch

​

Step 3: Link Your GitHub Account

1. Log in to your Pageo account
2. Go to your admin dashboard
3. Click on “Link GitHub” or navigate to GitHub settings
4. Enter your GitHub username
5. Click “Validate Repository”
6. Once validated, click “Link GitHub”

• Verify that your repository exists
• Check that pageo.json is present and valid
• Verify that the email in pageo.json matches your account email
• Import your profile configuration

​

Step 4: Set Up Webhooks (Automatic Syncing)

​

Step 4.1: Copy the Webhook URL

1. In your Pageo admin dashboard, go to GitHub Settings
2. Navigate to the “Webhook” tab
3. Copy the webhook URL (it will look like: https://pageo.me/api/github/webhook)

​

Step 4.2: Configure Webhook in GitHub

1. Go to your GitHub repository
2. Click on Settings (in the repository, not your account settings)
3. In the left sidebar, click Webhooks
4. Click Add webhook
5. Fill in the webhook details:
   • Payload URL: Paste the webhook URL you copied from Pageo
   • Content type: Select application/json
   • Secret: Leave empty for now (we’ll add this in the next step)
   • Which events: Select “Just the push event”
6. Make sure Active is checked
7. Click Add webhook

​

Step 4.3: Generate and Save Webhook Secret (Optional but Recommended)

1. In Pageo’s webhook settings, click Generate & Copy
2. The secret will be automatically copied to your clipboard
3. Go back to your GitHub webhook settings
4. Click on the webhook you just created
5. Scroll down to the Secret field
6. Paste the generated secret
7. Click Update webhook
8. Return to Pageo and click Save Secret

​

How It Works

1. You make changes to pageo.json in your GitHub repository
2. You commit and push the changes to the main branch
3. GitHub sends a webhook to Pageo when you push
4. Pageo verifies the webhook (if you saved a secret)
5. Pageo checks if pageo.json was modified in the push
6. Pageo fetches the updated pageo.json from GitHub
7. Pageo updates your profile automatically

​

Manual Sync

1. Go to GitHub Settings in your Pageo dashboard
2. Click on the “Webhook” tab
3. Click Sync from GitHub

​

Updating Your Profile

1. Edit pageo.json in your GitHub repository
2. Commit and push the changes
3. If webhooks are set up, your profile will update automatically
4. If not, use the manual sync button in Pageo

​

Unlinking GitHub

1. Go to GitHub Settings in your Pageo dashboard
2. Navigate to the “Delink” tab
3. Click Delink GitHub

​

Troubleshooting

​

”Repository not found” error

• Make sure your repository is named exactly as your GitHub username
• Verify the repository exists and is accessible
• Check that you’ve entered your GitHub username correctly (not your full name or email)

​

“pageo.json not found” error

• Ensure pageo.json exists in the root of your repository
• Check that the file is committed and pushed to the main branch
• Verify the filename is exactly pageo.json (case-sensitive)

​

“Email mismatch” error

• The email field in your pageo.json must match your Pageo account email exactly
• Update the email in pageo.json to match your account email
• Commit and push the changes

​

Webhook not triggering

• Verify the webhook URL is correct in GitHub
• Check that the webhook is set to trigger on “push” events
• Make sure you’re pushing to the main branch
• Ensure pageo.json was actually modified in the push
• Check GitHub’s webhook delivery logs for any errors

​

Profile not updating

• Try manually syncing from the Pageo dashboard
• Check that your pageo.json is valid JSON
• Verify all required fields are present
• Make sure you’re not exceeding limits (8 social links, 4 grid links)

​

Best Practices

1. Version control everything: Use Git commits to track changes to your profile
2. Test locally first: Validate your JSON before pushing
3. Use branches: Create a branch, test your changes, then merge to main
4. Save your webhook secret: It adds security to your webhook integration
5. Keep it simple: Only include fields you need—Pageo will handle the rest

​

JSON Schema Reference

​

Required Fields

• email: Your account email (must match Pageo account)
• profile.name: Your display name
• profile.role: Your role or title
• profile.bio: Your bio text
• socialLinks: Array of social links (max 8)
• gridLinks: Array of grid links (max 4)
• settings.layout: Either "list" or "grid"

​

Optional Fields

• profile.image: URL to your profile image
• profile.email: Contact email (different from account email)
• profile.imageName: Image filename
• socialLinks[].color: Custom color for social icon
• socialLinks[].title: Custom title for social link
• settings.showContactForm: Boolean to show/hide contact form

​

Auto-Generated Fields

• socialLinks[].order: Automatically set based on array position
• gridLinks[].id: Automatically set based on array position
• gridLinks[].order: Automatically set based on array position

​

Support

1. Check that your pageo.json follows the correct schema
2. Verify your repository name matches your GitHub username
3. Ensure all required fields are present
4. Try manually syncing to see if the issue is with webhooks