GitHub Integration & Developer Hub

🚀 Quick Setup

ℹ️

Before beginning, ensure you have a Sitemap.xml API Key and GitHub OAuth token with repo and workflow scopes.

1. Install the SDK

# Install via npm
npm install @sitemap/cli

# Or via yarn
yarn add @sitemap/cli

2. Configure Environment

                
                SITEMAP_API_KEY=sm_live_8x7K2p9Qm1vR4tYw
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
REPO_OWNER=your-org
REPO_NAME=your-repo
            

3. Initialize & Test

npx sitemap init --target github
npx sitemap generate --dry-run

⚙️ GitHub Actions Workflow

Add the following workflow to .github/workflows/sitemap.yml to automate sitemap generation on every push to main.

                
                name: Generate & Submit Sitemap

on:
  push:
    branches: [main]
  schedule: # Daily at 06:00 UTC
    - cron: '0 6 * * *'

jobs:
  sitemap:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install CLI
        run: npm ci && npx sitemap init
        env:
          SITEMAP_API_KEY: ${{ secrets.SITEMAP_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Generate & Push
        run: npx sitemap generate --auto-commit
        env:
          COMMIT_USERNAME: sitemap-bot
          COMMIT_EMAIL: bot@sitemap.xml
            

⚠️

Ensure GITHUB_TOKEN has contents: write permissions to auto-commit generated sitemaps.

📦 Official Repositories

@sitemap/cli JS

Command-line interface for sitemap generation, validation, and search engine submission.

⭐ 1.2k🍴 89📦 npm

@sitemap/core TS

Core parsing engine supporting XML, JSON, HTML, and video/image sitemap extensions.

⭐ 956🍴 42📦 npm

sitemap-go Go

High-performance Go library for streaming sitemap generation and URL indexing.

⭐ 678🍴 31📦 pkg.go.dev

sitemap-python Py

Python SDK with async support, FastAPI middleware, and Celery task integration.

⭐ 521🍴 27📦 PyPI

🔌 API & Webhook Reference

Programmatic control over sitemap generation, indexing status, and crawl requests.

Method	Endpoint	Description
POST	`/v1/sitemaps/generate`	Trigger manual sitemap build & submit
GET	`/v1/index/status`	Check indexing status across major search engines
POST	`/v1/crawl/request`	Force immediate crawl for new/updated URLs
GET	`/v1/analytics/coverage`	Retrieve coverage reports & crawl errors

Receive real-time notifications when sitemap events occur in your repository.

// POST payload example
{
  "event": "sitemap.generated",
  "repo": "org/repo",
  "urls_count": 1428,
  "submitted_to": ["google", "bing", "yandex"],
  "timestamp": "2025-01-15T08:32:11Z"
}

Connect your GitHub account securely using OAuth 2.0. We never store your GitHub password.

Authorization URL: https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID
Token exchange: POST https://github.com/login/oauth/access_token
Required scopes: repo, workflow, public_repo

🛟 Troubleshooting & Support

💡

Having issues with GitHub Actions failing to commit? Verify your token has contents: write and that your repository allows commits from GitHub Actions.

Common Issues

403 Forbidden: Ensure your API key has sitemap:write permissions in the dashboard.
Dry run vs Live: Use --dry-run to preview changes before committing to your repo.
Large repos: For >100k URLs, enable --stream mode to reduce memory usage.

Still stuck? Our developer community is here to help.

Join GitHub Discussions