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: 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 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" + } +}