fix: Grant All Permissions on All Projects mechanism (Issue #148)#149
Merged
Conversation
## Summary
Changed the permission migration mechanism to use SonarCloud's "Grant All Permissions on All Projects" approach, which grants admin permission at the organization level (automatically granting all permissions on all projects) instead of trying to replicate the complex per-group, per-permission structure that fails when groups don't exist in SonarCloud.
## Problem
The original permission migration mechanism iterated over all groups from SonarQube and tried to grant each specific permission (scan, admin, gateadmin, etc.) to each group on each project. This approach had multiple failure modes:
1. **Silent failures**: Permission grant errors were only logged at debug level, silently swallowed
2. **Group existence**: If a group didn't exist in SonarCloud, permissions weren't granted
3. **Edge cases**: Groups/users not available in SQC caused incomplete migrations
4. **Complexity**: Replicating granular permissions was error-prone and hard to debug
## Solution
### API Layer (`group-permissions.js`)
Added new function `grantAllPermissionsOnAllProjects()` that uses the 'admin' permission at org level, which automatically grants all permissions on all projects in SonarCloud:
```javascript
export async function grantAllPermissionsOnAllProjects(client, organization, groupName) {
await client.post('/api/permissions/add_group', null, {
params: { groupName, permission: 'admin', organization }
});
}
```
### Migration Layer (`migrate-global-permissions.js`)
Refactored to use the simplified mechanism:
- Primary: Grant 'admin' to 'Sonar Migration Admins' group
- Fallback: If that fails, grant to 'Anyone' group
- Throws error only if both attempts fail
### Project Permissions (`migrate-project-permissions.js`)
Changed to skip per-project permissions since the org-level admin permission already covers all projects. Added null-safe handling for projectPermissions parameter.
## Files Changed
| File | Change |
|------|--------|
| `api/permissions/helpers/group-permissions.js` | Added `grantAllPermissionsOnAllProjects()` function |
| `api/permissions/index.js` | Export new function |
| `api/permissions.js` | Export new function |
| `api-client/helpers/attach-perm-methods.js` | Attach new method to client |
| `migrators/permissions/helpers/migrate-global-permissions.js` | Simplified to use admin permission with fallback |
| `migrators/permissions/helpers/migrate-project-permissions.js` | Skipped (admin at org level covers all) |
## Regression Testing
Verified on SonarQube/SonarCloud with:
- SQ: 3 groups with global permissions found
- SC: 'Sonar Migration Admins' group confirmed with ['gateadmin', 'scan', 'admin', 'provisioning'] permissions
Log output confirmed successful migration:
```
Migrating global permissions using simplified 'Grant All Permissions on All Projects' mechanism
Successfully granted admin permission to 'Sonar Migration Admins' group
```
---
## New Documentation (5 files)
Added comprehensive documentation for new users and contributors:
### Easy Local Development Guide.md
- Beginner-friendly setup instructions
- Prerequisites, clone, build, run steps
- Troubleshooting section
- Config file templates
### Design Principles.md
- Folder-Centric Architecture
- Micro Files Over Monoliths
- Flat Over Nested
- Readable at a Glance
- Shared Libraries for Reuse
- Error Handling
- State Management
### Core Technologies.md
- Node.js and SEA packaging
- Protobuf encoding
- Winston logging
- Commander.js CLI
- Ajv schema validation
- Electron desktop GUI
- GitHub Actions CI/CD
### Business Value.md
- Time savings (no re-scanning)
- Data preservation metrics
- Risk reduction strategies
- Cost efficiency analysis
- Governance continuity
### Audit & Error Events Logging Strategy.md
- Winston-based logging architecture
- Log levels and destinations
- Structured logging format
- Error classification hierarchy
- Audit trail events
- Log rotation strategy
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
SummaryThis PR replaces the granular permission migration approach with a simplified org-level grant mechanism. Instead of attempting to replicate complex per-group, per-permission structures (which fails silently when groups don't exist in SonarCloud), it now:
The API changes are minimal (one new function + client binding), but the migration logic is significantly simplified. Also adds 5 comprehensive documentation files covering logging strategy, design principles, tech stack, business value, and local development setup. What reviewers should knowWhere to start:
Key decisions to understand:
Documentation changes:
|
Collaborator
Author
|
++ @okorach-sonar @okorach ok resolved, regression tested. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Changed the permission migration mechanism to use SonarCloud's "Grant All Permissions on All Projects" approach, which grants admin permission at the organization level (automatically granting all permissions on all projects) instead of trying to replicate the complex per-group, per-permission structure that fails when groups don't exist in SonarCloud.
Problem
The original permission migration mechanism iterated over all groups from SonarQube and tried to grant each specific permission to each group on each project. This caused silent failures when groups didn't exist in SonarCloud.
Solution
API Layer
grantAllPermissionsOnAllProjects()function that uses the 'admin' permission at org levelMigration Layer
migrateGlobalPermissions: Now grants 'admin' to 'Sonar Migration Admins' group with fallback to 'Anyone'migrateProjectPermissions: Skipped (admin at org level covers all projects)Files Changed
api/permissions/helpers/group-permissions.jsgrantAllPermissionsOnAllProjects()api/permissions/index.jsapi/permissions.jsapi-client/helpers/attach-perm-methods.jsmigrators/permissions/helpers/migrate-global-permissions.jsmigrators/permissions/helpers/migrate-project-permissions.jsRegression Testing
✅ Verified:
Sonar Migration Adminsgroup confirmed with['gateadmin', 'scan', 'admin', 'provisioning']permissionsNew Documentation (5 files)
Added comprehensive documentation:
Easy Local Development Guide.md- Beginner setup guideDesign Principles.md- Architecture patternsCore Technologies.md- Tech stack overviewBusiness Value.md- Value propositionAudit & Error Events Logging Strategy.md- Logging systemTest Plan
npm run package)🤖 Generated with Claude Code