GitHub Integration

GitHub App Architecture

Sitepins uses a GitHub App for secure, fine-grained repository access:

1. Installation Flow:

   • User installs GitHub App on repositories
   • App receives installation webhook
   • Installation data stored in backend

2. Authentication Strategy:

   • App-level authentication for repository operations
   • User-level authentication for personal data
   • JWT tokens for API requests

3. Permission Model:

   • Contents: Read & Write (for file operations)
   • Metadata: Read (for repository information)
   • Pull Requests: Read & Write (for collaboration)

Content Management Workflow

1. File Tree Retrieval:

// Fetch repository structure
const { data: trees } = useGetTreesQuery({
  owner: "username",
  repo: "repository",
  tree_sha: "main",
  recursive: "1",
});

2. Content Reading:

// Get file content with frontmatter parsing
const { data: content } = useGetContentQuery({
  owner: "username",
  repo: "repository",
  path: "content/blog/post.md",
  ref: "main",
  parser: true,
});

3. Content Writing:

// Update files with Git workflow
const [updateFiles] = useUpdateFilesMutation();
 
await updateFiles({
  owner: "username",
  repo: "repository",
  tree: "main",
  files: [
    {
      path: "content/blog/new-post.md",
      content: "---\ntitle: New Post\n---\n\nContent here...",
    },
  ],
  message: "Add new blog post",
});

Git Operations

The system implements a complete Git workflow:

1. Blob Creation: Convert file content to Git blobs
2. Tree Construction: Organize blobs into directory structure
3. Commit Creation: Create commit with proper attribution
4. Reference Update: Update branch to point to new commit

Intelligent Features

• Legacy Migration: Automatically migrates old folder structures
• Configuration Detection: Finds and loads site configuration
• Framework Recognition: Detects Next.js, Astro, Hugo, etc.
• Media Handling: Special processing for binary files