Organizations and teams quick start#

5-Minute Overview#

CloudForge now supports organizations and teams, just like GitHub. Here's the quick version:

For Users#

1. Create an org: POST /api/orgs with slug, display_name
2. Invite members to your org
3. Create teams to organize repo access
4. Add members to teams
5. Add repos to teams with permission levels (read/write/admin)

For Admins#

1. Commit the migration and component changes together.
2. Confirm the dependency-aware impact with node scripts/forge-release-impact.mjs.
3. Release through node scripts/forge-release-affected.mjs --sha <exact-sha>; the coordinator owns migration order, component activation, and evidence.
4. Verify the endpoints and release receipts, then monitor the owning components.

Common Tasks#

Create an Organization#

curl -X POST https://forge.smol.ai/api/orgs \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-corp",
    "display_name": "ACME Corporation",
    "description": "ACME's GitHub clone"
  }'

Add a Member to Org#

curl -X POST https://forge.smol.ai/api/orgs/acme-corp/members \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "role": "member"
  }'

Create a Team#

curl -X POST https://forge.smol.ai/api/orgs/acme-corp/teams \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "backend",
    "display_name": "Backend Engineers",
    "permission": "write"
  }'

Add Member to Team#

curl -X POST https://forge.smol.ai/api/orgs/acme-corp/teams/backend/members \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice"}'

Create Org Repo#

curl -X POST https://forge.smol.ai/api/orgs/acme-corp/repos \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-server",
    "description": "Our API",
    "visibility": "private"
  }'

visibility is required and accepts public, unlisted, or private.

Add Repo to Team#

curl -X POST https://forge.smol.ai/api/orgs/acme-corp/teams/backend/repos \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": "abc123...",
    "permission": "write"
  }'

Get Team Details (with members & repos)#

curl https://forge.smol.ai/api/orgs/acme-corp/teams/backend

List Org Repos (filtered by access)#

curl https://forge.smol.ai/api/orgs/acme-corp/repos

Permission Levels#

When adding repos to teams, choose one:

• read: Clone/view only
• write: Clone, push, create issues (typical dev)
• admin: Modify settings, delete repo (typically leads)

Roles#

Organization member roles:

• owner: Full control (created org automatically)
• admin: Can manage teams and repos
• member: Can access repos via team membership (no org management)

Default Team#

Every org gets a Members team automatically:

• Slug: members
• Permission: read
• Purpose: All org members can see repos
• Cannot delete

Important Notes#

Personal Repos Still Work#

• Create a repo as before: POST /api/repos
• You're the owner, no org needed
• Repos are at your username: /@username/repo-name

Org Repos Are Different#

• Created via POST /api/orgs/:org/repos
• Access via teams, not collaborators
• Located at /:org/repo-name
• Only org members can access

Access Control#

• Personal repo: Only you can see/edit (unless you add collaborators)
• Private org repo: Only org members with team access
• Public org repo: Anyone can view, only team members can edit

Cloning Org Repos#

# With HTTPS
git clone https://forge.smol.ai/acme-corp/api-server.git

# With SSH (if configured)
# SSH is not currently supported; use the HTTPS Smart HTTP URL above.

Troubleshooting#

"User is not an organization member"#

When adding someone to a team, they must first be an org member. Add to org first.

"Cannot delete the default Members team"#

The Members team is required. You cannot delete it.

"Cannot remove the last owner"#

Every org needs at least one owner. Promote someone to owner first.

Team member doesn't see repo#

1. Check user is in the org
2. Check user is in the team
3. Check team has access to the repo
4. Check team's permission level

Next Steps#

• Read the organizations and teams design for full API documentation.
• Read production deployment for deployment details.
• See the historical implementation summary for the original architecture overview.