Skip to content

Commit 9035900

Browse files
colby-swandalecolby-swandale
authored
Merge pull request #395 from rubygems/colby/organization-documentation
Organization documentation
2 parents 8a2c308 + 981f498 commit 9035900

File tree

12 files changed

+759
-191
lines changed

12 files changed

+759
-191
lines changed

‎_layouts/default.html‎

Lines changed: 212 additions & 188 deletions
Large diffs are not rendered by default.

‎credits.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Credits
4-
previous: /trusted-publishing/releasing-gems
4+
previous: /organizations/transferring-gems
55
next: /
66
---
77

‎organizations.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
layout: default
3+
title: Organizations
4+
url: /organizations
5+
previous: /trusted-publishing/releasing-gems
6+
next: /organizations/getting-started
7+
---
8+
9+
# Organizations
10+
11+
<div class="beta-banner">
12+
<span class="beta-banner__icon">⚠️</span>
13+
<strong class="beta-banner__title">Private Beta:</strong>
14+
<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:support@rubygems.org">support@rubygems.org</a>.</span>
15+
</div>
16+
17+
Organizations help teams and businesses collaborate, share gem ownership, manage permissions, and work together under a unified identity.
18+
19+
## What are Organizations?
20+
21+
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:
22+
23+
- **Maintain continuity** when team members change
24+
- **Control access** with role-based permissions
25+
- **Collaborate effectively** on gem development
26+
- **Establish identity** for your company or project
27+
28+
## Getting Started
29+
30+
Ready to create your organization? Follow our [Getting Started Guide](/organizations/getting-started) to set up your first organization in minutes.
31+
32+
### Quick Links
33+
34+
- [Create an Organization](/organizations/getting-started)
35+
- [Understanding Roles](/organizations/roles-and-permissions)
36+
- [Managing Members](/organizations/managing-members)
37+
- [Transferring Gems](/organizations/transferring-gems)
38+
39+
## Need Help?
40+
41+
- Contact [support@rubygems.org](mailto:support@rubygems.org) for assistance
42+
- Report issues on [GitHub](https://github.com/rubygems/rubygems.org/issues)

‎organizations/getting-started.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
layout: default
3+
title: Getting Started with Organizations
4+
url: /organizations/getting-started
5+
previous: /organizations
6+
next: /organizations/managing-members
7+
---
8+
9+
<div class="beta-banner">
10+
<span class="beta-banner__icon">⚠️</span>
11+
<strong class="beta-banner__title">Private Beta:</strong>
12+
<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:support@rubygems.org">support@rubygems.org</a>.</span>
13+
</div>
14+
15+
# Getting Started with Organizations
16+
17+
Create your first Organization and start collaborating on RubyGems.org in minutes.
18+
19+
## Before You Begin
20+
21+
To create an organization, you'll need:
22+
23+
- A RubyGems.org account with **multi-factor authentication (MFA)** enabled
24+
- At least one gem where you're listed as an owner
25+
26+
## Creating Your Organization
27+
28+
Navigate to your [dashboard](https://rubygems.org/dashboard) and click **Create Organization**.
29+
30+
### Step 1: Set Organization Details
31+
32+
Provide your Organization's information:
33+
34+
- **Handle**: Your unique identifier (selected from a list of gems the current user is listed as an owner of)
35+
- **Display Name**: How your Organization appears publicly (2-255 characters)
36+
37+
The handle becomes part of your organization URL: `rubygems.org/organizations/your-handle`
38+
39+
### Step 2: Select Gems to Transfer
40+
41+
If you own multiple gems, choose which ones to transfer to the Organization:
42+
43+
- Only gems where you're an owner appear in the list
44+
- Gems already belonging to other organizations are excluded
45+
- You can transfer additional gems later
46+
47+
**Important:** Once transferred, gems belong to the Organization. Individual ownership is replaced by organization membership.
48+
49+
### Step 3: Invite Team Members
50+
51+
Add your collaborators to the Organization:
52+
53+
**Automatic Suggestions:** We'll suggest users who co-own your selected gems. This makes it easy to maintain existing collaborations.
54+
55+
**Assign Roles:** Choose the appropriate role for each member:
56+
57+
- **Owner**: Full organization control
58+
- **Admin**: Gem and member management
59+
- **Maintainer**: Basic access and gem operations
60+
- **Outside Collaborator**: Limited access, retains personal ownership of gems and is not a member of the orgnization
61+
62+
### Step 4: Confirm and Create
63+
64+
Review your organization setup:
65+
66+
- Organization name and handle
67+
- Selected gems for transfer
68+
- Invited members and their roles
69+
70+
Click **Create Organization** to finalize your Organization. You'll see:
71+
72+
- Your Organization is created
73+
- Selected gems are transferred
74+
- Members receive an email to join your Organization.
75+
- You're redirected to your organization page
76+
77+
## After Creation
78+
79+
### Immediate Next Steps
80+
81+
1. **Wait for Invitations**: Members must accept their invitations to join the Organization
82+
2. **Configure Settings**: Visit organization settings to customize further
83+
3. **Transfer More Gems**: Add additional gems as needed
84+
85+
### Managing Your Organization
86+
87+
Access your Organization at `rubygems.org/organizations/your-handle` to:
88+
89+
- View organization gems
90+
- Manage members
91+
- Update settings
92+
- Monitor activity
93+
94+
### API and Automation
95+
96+
Currently, onboarding an Organization must be done through the web interface. API support may be added in future.
97+
98+
## Troubleshooting
99+
100+
### Can't Create Organization?
101+
- Verify MFA is enabled on your account
102+
- Ensure you own at least one gem (for gem-based organizations)
103+
- Check that your desired handle isn't already taken
104+
105+
### Invitation Issues?
106+
- Invitations expire after a set period
107+
- Members must have RubyGems.org accounts
108+
- Check spam folders for invitation emails
109+
110+
### Need More Help?
111+
112+
- Review our [Roles and Permissions](/organizations/roles-and-permissions) guide
113+
- Learn about [Managing Members](/organizations/managing-members)
114+
- Contact [support@rubygems.org](mailto:support@rubygems.org) for assistance
115+
116+
---
117+
118+
Ready to collaborate? [Create your Organization](https://rubygems.org/organizations/new) now.

‎organizations/managing-members.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Managing Organization Members
3+
layout: default
4+
url: /organizations/managing-members
5+
previous: /organizations/getting-started
6+
next: /organizations/roles-and-permissions
7+
---
8+
9+
# Managing Organization Members
10+
11+
<div class="beta-banner">
12+
<span class="beta-banner__icon">⚠️</span>
13+
<strong class="beta-banner__title">Private Beta:</strong>
14+
<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:support@rubygems.org">support@rubygems.org</a>.</span>
15+
</div>
16+
17+
This guide covers inviting new members, managing existing ones, and handling common membership scenarios.
18+
19+
## Viewing Members
20+
21+
Access your member list from your organization page:
22+
23+
1. Navigate to `rubygems.org/organizations/your-handle`
24+
2. Click **Members** in the navigation
25+
3. View all current members with their roles and join dates
26+
27+
The member list shows:
28+
- Member username
29+
- Current role (Owner, Admin, or Maintainer)
30+
31+
## Inviting New Members
32+
33+
### Who Can Invite?
34+
- **Owners** can invite members at any level
35+
- **Admins** can invite new Admins and Maintainers
36+
- **Maintainers** cannot send invitations
37+
38+
### Sending Invitations
39+
40+
1. Click **Invite** from the members page
41+
2. Enter the invitee's username
42+
3. Select their role
43+
5. Click **Invite**
44+
45+
### Invitation Process
46+
47+
**What happens next:**
48+
- Invitee receives an email with a link to join the Organization
49+
- MFA must be enabled before joining
50+
- Invitation expires after 7 days
51+
- You'll see pending invitations in your member list
52+
53+
**Tracking invitations:**
54+
- Pending invitations appear with a "Pending" status
55+
- See when invitations were sent
56+
- Resend or cancel pending invitations
57+
58+
## Managing Existing Members
59+
60+
### Changing Roles
61+
62+
Adjust member permissions as responsibilities evolve:
63+
64+
1. Find the member in your list
65+
3. Select the new role from the dropdown
66+
4. Confirm the change
67+
68+
**Important considerations:**
69+
- Only Owners can change Owner roles
70+
- Admins cannot modify Owner permissions
71+
- Changes take effect immediately
72+
73+
### Removing Members
74+
75+
When team members leave or no longer need access:
76+
77+
1. Locate the member to remove
78+
2. Click **Delete**
79+
3. Confirm the removal
80+
81+
**Removal rules:**
82+
- Owners can remove anyone except themselves
83+
- Admins can remove Maintainers and other Admins
84+
- Members cannot remove themselves
85+
- Removed members lose all organization access immediately
86+
87+
### API and Automation
88+
89+
Currently, managing Organization Members must be done through the web interface. API support may be added in future.
90+
91+
## Troubleshooting
92+
93+
### Invitation Not Received
94+
- Check spam/junk folders
95+
- Resend invitation if needed
96+
- Confirm recipient has email access
97+
98+
### Cannot Change Roles
99+
- Verify you have appropriate permissions
100+
- Owners cannot be modified by Admins
101+
- Contact an Owner for help
102+
103+
### Member Cannot Access Gems
104+
- Confirm MFA is enabled
105+
- Verify membership is active (not pending)
106+
- Check organization gem list
107+
- Review member's role permissions
108+
109+
### Accidental Removal
110+
- Removed members must be re-invited
111+
- Previous role not automatically restored
112+
- Act quickly to minimize disruption
113+
114+
## Getting Help
115+
116+
- Review our [Roles and Permissions](/organizations/roles-and-permissions) guide
117+
- Contact [support@rubygems.org](mailto:support@rubygems.org) for complex issues
118+
119+
---
120+
121+
Keep your team organized and secure with proper member management.

‎organizations/roles-and-permissions.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
url: /organizations/roles-and-permissions
3+
title: Organization Roles and Permissions
4+
layout: default
5+
previous: /organizations/managing-members
6+
next: /organizations/transferring-gems
7+
---
8+
9+
# Organization Roles and Permissions
10+
11+
<div class="beta-banner">
12+
<span class="beta-banner__icon">⚠️</span>
13+
<strong class="beta-banner__title">Private Beta:</strong>
14+
<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:support@rubygems.org">support@rubygems.org</a>.</span>
15+
</div>
16+
17+
Organizations use role-based access control to ensure team members have appropriate permissions. Understanding these roles helps you build an effective collaboration structure.
18+
19+
## Available Roles
20+
21+
### Owner
22+
The highest level of access. Owners have complete control over the organization.
23+
24+
**Best for:** Organization founders, CTOs, or team leads who need full control.
25+
26+
### Admin
27+
Administrators handle day-to-day organization management.
28+
29+
**Best for:** Senior developers, team managers, or trusted contributors who manage gems and team members.
30+
31+
### Maintainer
32+
The base level of organization membership with essential access.
33+
34+
**Best for:** Developers who need to work with organization gems but don't require administrative privileges.
35+
36+
## Permission Comparison
37+
38+
| Action | Owner | Admin | Maintainer |
39+
|--------|--------|--------|--------|
40+
| View organization info | ✓ | ✓ | ✓ |
41+
| Push gem versions | ✓ | ✓ | ✓ |
42+
| Yank gem versions | ✓ | ✓ | ✓ |
43+
| View member list | ✓ | ✓ | ✓ |
44+
| Invite members | ✓ | ✓ | ✗ |
45+
| Remove members | ✓ | ✓¹ | ✗ |
46+
| Change member roles | ✓ | ✓¹ | ✗ |
47+
| Add gems | ✓ | ✓ | ✗ |
48+
| Remove gems | ✓ | ✗ | ✗ |
49+
| Update organization | ✓ | ✗ | ✗ |
50+
| Delete organization | ✓ | ✗ | ✗ |
51+
52+
¹ *Admins cannot modify or remove Owners*
53+
54+
## Next Steps
55+
56+
- Learn about [Managing Organization Members](/organizations/managing-members)
57+
- Understand [Transferring Gems](/organizations/transferring-gems) to organizations
58+
59+
---
60+
61+
Questions about roles? Contact [support@rubygems.org](mailto:support@rubygems.org) for assistance.

0 commit comments

Comments
 (0)