From 2a0220a9fd959f96ce4ee4050c900a5ba3fa31da Mon Sep 17 00:00:00 2001 From: Tobias Wilken Date: Fri, 26 Dec 2025 08:04:28 +0100 Subject: [PATCH 1/3] docs: add GitHub App manifest files Add manifest files for both WorldDriven GitHub Apps: - worlddriven.json: Main app for PR voting and auto-merge - worlddriven-migrate.json: Migration app for repository transfers The migrate app uses a separate, minimal permission set (only administration + metadata) to enable repository transfers without requiring the main app to have elevated permissions. This supports the new migration approach documented in issue #23, which uses GitHub App installation instead of collaborator invitations to obtain the admin permission needed for repository transfers. Relates to #23 --- github-apps/README.md | 84 ++++++++++++++++++++++++++++ github-apps/worlddriven-migrate.json | 16 ++++++ github-apps/worlddriven.json | 28 ++++++++++ 3 files changed, 128 insertions(+) create mode 100644 github-apps/README.md create mode 100644 github-apps/worlddriven-migrate.json create mode 100644 github-apps/worlddriven.json diff --git a/github-apps/README.md b/github-apps/README.md new file mode 100644 index 0000000..0b262e4 --- /dev/null +++ b/github-apps/README.md @@ -0,0 +1,84 @@ +# WorldDriven GitHub Apps + +This directory contains the manifest files for WorldDriven's GitHub Apps. These manifests define the permissions, events, and configuration for each app. + +## Apps Overview + +| App | Purpose | Permissions | +|-----|---------|-------------| +| [worlddriven](worlddriven.json) | PR voting and auto-merge | checks, contents, issues, pull_requests, statuses, workflows | +| [worlddriven-migrate](worlddriven-migrate.json) | One-time repository transfer | administration, metadata | + +## WorldDriven (Main App) + +The main app handles the democratic PR management system: +- Monitors pull requests and reviews +- Calculates voting weights based on contributions +- Automatically merges PRs when voting threshold is reached +- Posts status updates and comments + +**Install**: [github.com/apps/worlddriven](https://github.com/apps/worlddriven) + +## WorldDriven Migrate + +A minimal app for transferring repositories to the worlddriven org: +- Only used during repository migration +- Requires Administration permission to perform transfers +- Can be uninstalled after migration completes + +**Install**: [github.com/apps/worlddriven-migrate](https://github.com/apps/worlddriven-migrate) + +## Why Two Apps? + +We use separate apps to follow the principle of least privilege: + +1. **Trust**: Users are more likely to install an app with minimal permissions +2. **Security**: The main app doesn't need admin access for normal operations +3. **Clarity**: Each app has a clear, single purpose +4. **Transparency**: Users know exactly why each permission is needed + +## Using Manifests + +These manifests can be used with GitHub's [App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) to create or recreate the apps. + +### Creating an App from Manifest + +1. Navigate to GitHub organization settings +2. Go to Developer settings > GitHub Apps > New GitHub App +3. Or use the manifest flow programmatically: + +```html +
+ + +
+``` + +### Manifest Parameters + +| Field | Description | +|-------|-------------| +| `name` | Display name of the app | +| `url` | Homepage URL | +| `hook_attributes.url` | Webhook endpoint URL | +| `description` | App description shown to users | +| `public` | Whether app can be installed by anyone | +| `default_events` | GitHub events the app subscribes to | +| `default_permissions` | Permissions requested by the app | + +## Updating Apps + +GitHub Apps cannot be updated via API. To change permissions or settings: + +1. Go to [github.com/organizations/worlddriven/settings/apps](https://github.com/organizations/worlddriven/settings/apps) +2. Select the app to modify +3. Update settings manually +4. Update the manifest file in this repository to keep documentation in sync + +**Note**: When permissions are added, existing installations must approve the new permissions. + +## References + +- [GitHub App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) +- [Permissions for GitHub Apps](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps) +- [Choosing Permissions](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app) diff --git a/github-apps/worlddriven-migrate.json b/github-apps/worlddriven-migrate.json new file mode 100644 index 0000000..56863a6 --- /dev/null +++ b/github-apps/worlddriven-migrate.json @@ -0,0 +1,16 @@ +{ + "name": "WorldDriven Migrate", + "url": "https://www.worlddriven.org/migrate", + "hook_attributes": { + "url": "https://www.worlddriven.org/api/webhooks/migrate" + }, + "description": "One-time repository migration to the worlddriven organization.\n\nThis app enables automated transfer of your repository to the worlddriven org after your migration PR has been approved by the community.\n\nHow It Works:\n1. Create a PR adding your repository to REPOSITORIES.md\n2. Wait for community approval through worlddriven voting\n3. Install this app on your repository\n4. Your repository is automatically transferred to the worlddriven org\n5. The PR auto-merges once the transfer completes\n\nThis app only requires Administration permission to perform the one-time transfer. You can uninstall it after migration is complete.\n\nNote: This is a separate app from the main WorldDriven app to keep permissions minimal. The main app handles PR voting and auto-merge; this app only handles repository transfers.", + "public": true, + "default_events": [ + "installation_repositories" + ], + "default_permissions": { + "administration": "write", + "metadata": "read" + } +} diff --git a/github-apps/worlddriven.json b/github-apps/worlddriven.json new file mode 100644 index 0000000..34be8af --- /dev/null +++ b/github-apps/worlddriven.json @@ -0,0 +1,28 @@ +{ + "name": "WorldDriven", + "url": "https://www.worlddriven.org", + "hook_attributes": { + "url": "https://www.worlddriven.org/api/webhooks/github" + }, + "redirect_url": "https://www.worlddriven.org/auth/callback", + "callback_urls": [ + "https://www.worlddriven.org/auth/callback" + ], + "setup_url": "https://www.worlddriven.org/setup", + "description": "World Driven - Democratic Pull Request Management Through Contribution-Based Voting.\n\nWorld Driven transforms how open source projects handle pull requests by implementing a fair, transparent, and automated merge system based on contributor participation.\n\nHow It Works:\n- Pull requests are automatically merged after a configurable time period (default: 10 days)\n- Contributors can vote on PRs through GitHub's native review system\n- Approve a review to speed up the merge\n- Request Changes to slow it down or block the merge\n- Vote weight is proportional to contributions to the project\n\nPerfect for open source projects with distributed maintainership, teams wanting democratic code review processes, and communities prioritizing contributor empowerment.", + "public": true, + "default_events": [ + "pull_request", + "pull_request_review", + "push" + ], + "default_permissions": { + "checks": "write", + "contents": "write", + "issues": "write", + "metadata": "read", + "pull_requests": "write", + "statuses": "write", + "workflows": "write" + } +} From 8cdceb4902a2f5665fc1b094e233d20406fccd25 Mon Sep 17 00:00:00 2001 From: Tobias Wilken Date: Fri, 26 Dec 2025 10:48:04 +0100 Subject: [PATCH 2/3] ci: run drift detection on all PRs Remove path filter so drift detection runs on every PR, not just those modifying REPOSITORIES.md. This ensures the repository setup is verified to be consistent regardless of what files change. --- .github/workflows/drift-detection.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/workflows/drift-detection.yml b/.github/workflows/drift-detection.yml index 06f3a0b..f73910a 100644 --- a/.github/workflows/drift-detection.yml +++ b/.github/workflows/drift-detection.yml @@ -2,10 +2,6 @@ name: Repository Drift Detection on: pull_request: - paths: - - 'REPOSITORIES.md' - - 'scripts/**' - - '.github/workflows/drift-detection.yml' jobs: detect-drift: From fc7c2f35659bb3f43476d659c7d55a92c4192ef9 Mon Sep 17 00:00:00 2001 From: Tobias Wilken Date: Fri, 26 Dec 2025 14:07:58 +0100 Subject: [PATCH 3/3] chore: remove test migration entry Remove the test entry with Origin field since the original migration approach (collaborator invitation) cannot work for personal repositories. The new migration approach using a GitHub App will be tested separately once the worlddriven-migrate app is created. --- REPOSITORIES.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/REPOSITORIES.md b/REPOSITORIES.md index ba95e86..2e3abbc 100644 --- a/REPOSITORIES.md +++ b/REPOSITORIES.md @@ -116,8 +116,3 @@ Track implementation progress in GitHub issue #9. ## webapp - Description: Web application interface for worlddriven - Topics: webapp, web, frontend, worlddriven - -## test -- Description: Test repository for migration automation -- Topics: test, migration, automation -- Origin: TooAngel/worlddriven-migration-test