Organization documentation

credits.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Credits
-previous: /trusted-publishing/releasing-gems
+previous: /organizations/transferring-gems
 next: /
 ---
 

organizations.md

@@ -0,0 +1,42 @@
+---
+layout: default
+title: Organizations
+url: /organizations
+previous: /trusted-publishing/releasing-gems
+next: /organizations/getting-started
+---
+
+# Organizations
+
+<div class="beta-banner">
+  <span class="beta-banner__icon">⚠️</span>
+  <strong class="beta-banner__title">Private Beta:</strong>
+  <span class="beta-banner__text">Organizations are currently in limited private beta testing. If you're interested in joining the beta program, please contact <a href="mailto:[email protected]">[email protected]</a>.</span>
+</div>
+
+Organizations help teams and businesses collaborate, share gem ownership, manage permissions, and work together under a unified identity.
+
+## What are Organizations?
+
+Organizations provide a shared space for multiple users to collectively manage RubyGems. Instead of individual ownership, gems belong to the organization, making it easier to:
+
+- **Maintain continuity** when team members change
+- **Control access** with role-based permissions
+- **Collaborate effectively** on gem development
+- **Establish identity** for your company or project
+
+## Getting Started
+
+Ready to create your organization? Follow our [Getting Started Guide](/organizations/getting-started) to set up your first organization in minutes.
+
+### Quick Links
+
+- [Create an Organization](/organizations/getting-started)
+- [Understanding Roles](/organizations/roles-and-permissions)
+- [Managing Members](/organizations/managing-members)
+- [Transferring Gems](/organizations/transferring-gems)
+
+## Need Help?
+
+- Contact [[email protected]](mailto:[email protected]) for assistance
+- Report issues on [GitHub](https://github.com/rubygems/rubygems.org/issues)

organizations/getting-started.md

@@ -0,0 +1,118 @@
+---
+layout: default
+title: Getting Started with Organizations
+url: /organizations/getting-started
+previous: /organizations
+next: /organizations/managing-members
+---
+
+<div class="beta-banner">
+  <span class="beta-banner__icon">⚠️</span>
+  <strong class="beta-banner__title">Private Beta:</strong>
+  <span class="beta-banner__text">Organizations are currently in limited private beta testing. If you're interested in joining the beta program, please contact <a href="mailto:[email protected]">[email protected]</a>.</span>
+</div>
+
+# Getting Started with Organizations
+
+Create your first Organization and start collaborating on RubyGems.org in minutes.
+
+## Before You Begin
+
+To create an organization, you'll need:
+
+- A RubyGems.org account with **multi-factor authentication (MFA)** enabled
+- At least one gem where you're listed as an owner
+
+## Creating Your Organization
+
+Navigate to your [dashboard](https://rubygems.org/dashboard) and click **Create Organization**.
+
+### Step 1: Set Organization Details
+
+Provide your Organization's information:
+
+- **Handle**: Your unique identifier (selected from a list of gems the current user is listed as an owner of)
+- **Display Name**: How your Organization appears publicly (2-255 characters)
+
+The handle becomes part of your organization URL: `rubygems.org/organizations/your-handle`
+
+### Step 2: Select Gems to Transfer
+
+If you own multiple gems, choose which ones to transfer to the Organization:
+
+- Only gems where you're an owner appear in the list
+- Gems already belonging to other organizations are excluded
+- You can transfer additional gems later
+
+**Important:** Once transferred, gems belong to the Organization. Individual ownership is replaced by organization membership.
+
+### Step 3: Invite Team Members
+
+Add your collaborators to the Organization:
+
+**Automatic Suggestions:** We'll suggest users who co-own your selected gems. This makes it easy to maintain existing collaborations.
+
+**Assign Roles:** Choose the appropriate role for each member:
+
+- **Owner**: Full organization control
+- **Admin**: Gem and member management
+- **Maintainer**: Basic access and gem operations
+- **Outside Collaborator**: Limited access, retains personal ownership of gems and is not a member of the orgnization
+
+### Step 4: Confirm and Create
+
+Review your organization setup:
+
+- Organization name and handle
+- Selected gems for transfer
+- Invited members and their roles
+
+Click **Create Organization** to finalize your Organization. You'll see:
+
+- Your Organization is created
+- Selected gems are transferred
+- Members receive an email to join your Organization.
+- You're redirected to your organization page
+
+## After Creation
+
+### Immediate Next Steps
+
+1. **Wait for Invitations**: Members must accept their invitations to join the Organization
+2. **Configure Settings**: Visit organization settings to customize further
+3. **Transfer More Gems**: Add additional gems as needed
+
+### Managing Your Organization
+
+Access your Organization at `rubygems.org/organizations/your-handle` to:
+
+- View organization gems
+- Manage members
+- Update settings
+- Monitor activity
+
+### API and Automation
+
+Currently, onboarding an Organization must be done through the web interface. API support may be added in future.
+
+## Troubleshooting
+
+### Can't Create Organization?
+- Verify MFA is enabled on your account
+- Ensure you own at least one gem (for gem-based organizations)
+- Check that your desired handle isn't already taken
+
+### Invitation Issues?
+- Invitations expire after a set period
+- Members must have RubyGems.org accounts
+- Check spam folders for invitation emails
+
+### Need More Help?
+
+- Review our [Roles and Permissions](/organizations/roles-and-permissions) guide
+- Learn about [Managing Members](/organizations/managing-members)
+- Contact [[email protected]](mailto:[email protected]) for assistance
+
+---
+
+Ready to collaborate? [Create your Organization](https://rubygems.org/organizations/new) now.

organizations/managing-members.md

@@ -0,0 +1,121 @@
+---
+title: Managing Organization Members
+layout: default
+url: /organizations/managing-members
+previous: /organizations/getting-started
+next: /organizations/roles-and-permissions
+---
+
+# Managing Organization Members
+
+<div class="beta-banner">
+  <span class="beta-banner__icon">⚠️</span>
+  <strong class="beta-banner__title">Private Beta:</strong>
+  <span class="beta-banner__text">Organizations are currently in limited private beta testing. If you're interested in joining the beta program, please contact <a href="mailto:[email protected]">[email protected]</a>.</span>
+</div>
+
+This guide covers inviting new members, managing existing ones, and handling common membership scenarios.
+
+## Viewing Members
+
+Access your member list from your organization page:
+
+1. Navigate to `rubygems.org/organizations/your-handle`
+2. Click **Members** in the navigation
+3. View all current members with their roles and join dates
+
+The member list shows:
+- Member username
+- Current role (Owner, Admin, or Maintainer)
+
+## Inviting New Members
+
+### Who Can Invite?
+- **Owners** can invite members at any level
+- **Admins** can invite new Admins and Maintainers
+- **Maintainers** cannot send invitations
+
+### Sending Invitations
+
+1. Click **Invite** from the members page
+2. Enter the invitee's username
+3. Select their role
+5. Click **Invite**
+
+### Invitation Process
+
+**What happens next:**
+- Invitee receives an email with a link to join the Organization
+- MFA must be enabled before joining
+- Invitation expires after 7 days
+- You'll see pending invitations in your member list
+
+**Tracking invitations:**
+- Pending invitations appear with a "Pending" status
+- See when invitations were sent
+- Resend or cancel pending invitations
+
+## Managing Existing Members
+
+### Changing Roles
+
+Adjust member permissions as responsibilities evolve:
+
+1. Find the member in your list
+3. Select the new role from the dropdown
+4. Confirm the change
+
+**Important considerations:**
+- Only Owners can change Owner roles
+- Admins cannot modify Owner permissions
+- Changes take effect immediately
+
+### Removing Members
+
+When team members leave or no longer need access:
+
+1. Locate the member to remove
+2. Click **Delete**
+3. Confirm the removal
+
+**Removal rules:**
+- Owners can remove anyone except themselves
+- Admins can remove Maintainers and other Admins
+- Members cannot remove themselves
+- Removed members lose all organization access immediately
+
+### API and Automation
+
+Currently, managing Organization Members must be done through the web interface. API support may be added in future.
+
+## Troubleshooting
+
+### Invitation Not Received
+- Check spam/junk folders
+- Resend invitation if needed
+- Confirm recipient has email access
+
+### Cannot Change Roles
+- Verify you have appropriate permissions
+- Owners cannot be modified by Admins
+- Contact an Owner for help
+
+### Member Cannot Access Gems
+- Confirm MFA is enabled
+- Verify membership is active (not pending)
+- Check organization gem list
+- Review member's role permissions
+
+### Accidental Removal
+- Removed members must be re-invited
+- Previous role not automatically restored
+- Act quickly to minimize disruption
+
+## Getting Help
+
+- Review our [Roles and Permissions](/organizations/roles-and-permissions) guide
+- Contact [[email protected]](mailto:[email protected]) for complex issues
+
+---
+
+Keep your team organized and secure with proper member management.

organizations/roles-and-permissions.md

@@ -0,0 +1,61 @@
+---
+url: /organizations/roles-and-permissions
+title: Organization Roles and Permissions
+layout: default
+previous: /organizations/managing-members
+next: /organizations/transferring-gems
+---
+
+# Organization Roles and Permissions
+
+<div class="beta-banner">
+  <span class="beta-banner__icon">⚠️</span>
+  <strong class="beta-banner__title">Private Beta:</strong>
+  <span class="beta-banner__text">Organizations are currently in limited private beta testing. If you're interested in joining the beta program, please contact <a href="mailto:[email protected]">[email protected]</a>.</span>
+</div>
+
+Organizations use role-based access control to ensure team members have appropriate permissions. Understanding these roles helps you build an effective collaboration structure.
+
+## Available Roles
+
+### Owner
+The highest level of access. Owners have complete control over the organization.
+
+**Best for:** Organization founders, CTOs, or team leads who need full control.
+
+### Admin
+Administrators handle day-to-day organization management.
+
+**Best for:** Senior developers, team managers, or trusted contributors who manage gems and team members.
+
+### Maintainer
+The base level of organization membership with essential access.
+
+**Best for:** Developers who need to work with organization gems but don't require administrative privileges.
+
+## Permission Comparison
+
+| Action | Owner | Admin | Maintainer |
+|--------|--------|--------|--------|
+| View organization info | ✓ | ✓ | ✓ |
+| Push gem versions | ✓ | ✓ | ✓ |
+| Yank gem versions | ✓ | ✓ | ✓ |
+| View member list | ✓ | ✓ | ✓ |
+| Invite members | ✓ | ✓ | ✗ |
+| Remove members | ✓ | ✓¹ | ✗ |
+| Change member roles | ✓ | ✓¹ | ✗ |
+| Add gems | ✓ | ✓ | ✗ |
+| Remove gems | ✓ | ✗ | ✗ |
+| Update organization | ✓ | ✗ | ✗ |
+| Delete organization | ✓ | ✗ | ✗ |
+
+¹ *Admins cannot modify or remove Owners*
+
+## Next Steps
+
+- Learn about [Managing Organization Members](/organizations/managing-members)
+- Understand [Transferring Gems](/organizations/transferring-gems) to organizations
+
+---
+
+Questions about roles? Contact [[email protected]](mailto:[email protected]) for assistance.