> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pageo.me/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration & Webhooks

> Sync your Pageo profile directly from your GitHub repository

Sync your Pageo profile directly from your GitHub repository. Manage your links, profile information, and settings as code—version controlled, developer-friendly, and automatically synced.

## Overview

With GitHub integration, you can:

* 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

Before you begin, make sure you have:

* 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](https://github.com) 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:

```json theme={null}
{
  "email": "your-email@example.com",
  "profile": {
    "name": "Your Name",
    "role": "Your Role",
    "bio": "Your bio here",
    "image": "https://example.com/your-image.jpg",
    "email": "your-email@example.com"
  },
  "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"

Pageo will:

* 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)

After linking your GitHub account, you can set up webhooks to automatically sync your profile whenever you push changes to your repository.

### 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)

The webhook secret adds an extra layer of security by verifying that webhook requests are actually coming from GitHub.

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**

<Note>
  Saving the secret is optional. Webhooks will work without it, but won't verify
  the request signature for security.
</Note>

## How It Works

Once set up, here's what happens:

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

Your profile will be updated within seconds of pushing to GitHub.

## Manual Sync

If you don't want to set up webhooks, or if webhooks aren't working, you can manually sync your profile:

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

This will fetch the latest version of `pageo.json` from your repository and update your profile.

## Updating Your Profile

To update 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

If you want to stop using GitHub integration:

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

<Warning>
  This will disconnect your GitHub repository. Your current profile
  configuration will remain, but it will no longer sync with GitHub. You'll need
  to manage your profile through the Pageo dashboard after delinking.
</Warning>

## 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

You don't need to include these—Pageo generates them automatically:

* `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

If you encounter issues not covered here:

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

For additional help, contact support or check the changelog for recent updates.