Manage groups

This feature is rolling out gradually

Overview

Groups help you organize your team and control access to your organization’s resources. By assigning team members to groups and granting those groups specific permissions, you can manage access at scale without handling permissions for each person individually.

Benefits of using groups:

• Manage access for multiple people at once
• Organize your team by function, department, or project
• Simplify onboarding and offboarding
• Maintain consistent permissions across resources

Groups overview

Understanding Ona Resources

Before diving into groups, it’s important to understand the resources you’ll be managing access to:

Projects: Configuration templates that define how development environments are set up. Projects are linked to Git repositories and specify settings like devcontainer paths, environment classes, and automation files.

Runners: The compute infrastructure (such as AWS EC2 instances, GCP machines, or local computers) that hosts and executes your development environments.

Environments: The actual running development workspaces created from projects. Environments run on runners and provide isolated spaces for development work.

How they work together: When someone creates an environment from a project, that environment runs on a runner. Projects define what the environment should be, and runners provide where it runs.

How Access Control Works

Default Access

When you create a new project or runner, it’s automatically accessible to:

• You (the creator) - with Editor permissions for projects, Admin permissions for runners
• All organization administrators - with Admin permissions

Resources are not shared with your entire organization by default. You must explicitly share them with groups or grant organization-wide access.

Why Groups?

Without groups, sharing a resource with your team would require either:

• Making team members organization administrators (giving them more access than needed)
• Leaving resources accessible only to admins (blocking team collaboration)

Groups solve this by letting you:

• Grant access to multiple people at once
• Organize your team by function, department, or project
• Maintain consistent permissions across resources
• Simplify onboarding and offboarding

Critical: Projects and Runners Must Both Be Accessible

For team members to use a project, they must have access to both the project itself and at least one runner that the project can use.

Projects can be configured to use multiple runners through environment classes. If a team member has access to a project but not to any of its associated runners, they can see the project but cannot create environments with it.

Before sharing a project, ensure that team members also have access to the appropriate runners. The Share dialog will display warnings when this might be an issue.

Access dependency warning

Creating and Managing Groups

Create a New Group

1. Navigate to Settings → Members
2. Select the Groups tab
3. Click New Group
4. Enter a group name
5. Add an optional description to help others understand the group’s purpose
6. Optionally add team members during creation
7. Click Create

Create a new group

Add Members to a Group

1. Go to Settings → Members → Groups
2. Click on the group you want to modify
3. Click Add People
4. Search for and select the team members you want to add
5. Click Add to confirm

You can add multiple people at once. All selected members will immediately gain access to any resources shared with the group.

Add members to a group

Edit Group Details

1. Navigate to the group’s detail page
2. Click the ⋯ (more actions) menu
3. Select Edit
4. Update the group name or description
5. Click Save

Remove Members from a Group

1. Open the group’s detail page
2. Find the member you want to remove in the members table
3. Click the checkbox next to their name (you can select multiple members)
4. Click Remove
5. Confirm the removal

When you remove someone from a group, they immediately lose access to all resources shared exclusively with that group. If the resource is also shared with other groups they belong to, or with everyone in the organization, they will retain access through those channels.

Group details and member management

Delete a Group

Deleting a group removes all its members and revokes the group’s access to all resources.

1. Navigate to the group’s detail page
2. Click the ⋯ (more actions) menu
3. Select Delete
4. Confirm the deletion

This action cannot be undone. Members will lose access to resources that were shared only with this group.

Roles and Permissions

When you assign a role to a group on a resource, all members of that group receive the permissions associated with that role.

Project Roles

The following table outlines the specific permissions for each role on projects:

Permission	User	Editor	Admin
Read Access
Read project (view details, settings, configuration)	✅	✅	✅
Read secrets (names only, not values)	✅	✅	✅
Read environment classes (see which runners the project uses)	✅	✅	✅
Read prebuilds (view prebuild configurations and history)	✅	✅	✅
Write Access
Update project (modify settings and configuration)	❌	✅	✅
Delete project	❌	✅	✅
Create/update/delete secrets (full access including values)	❌	✅	✅
Create/update/delete environment classes (configure runners)	❌	✅	✅
Create/update/delete prebuilds	❌	✅	✅
Admin Access
Grant access (share project with groups)	❌	❌	✅

Editors can delete projects. Grant Editor access only to trusted team members who need full management capabilities.

Runner Roles

The following table outlines the specific permissions for each role on runners:

Permission	User	Admin
Read Access
Read runner (view details, status, configuration)	✅	✅
Read environment classes (view available machine types)	✅	✅
Read SCM integrations (view source control integrations)	✅	✅
Read/use LLM integrations (view and use AI/LLM features)	✅	✅
Usage
Create environments on this runner	✅	✅
Create agent executions (use AI agent features)	✅	✅
Create host authentication tokens	✅	✅
Write Access
Update runner (modify configuration and settings)	❌	✅
Delete runner	❌	✅
Create/update/delete environment classes	❌	✅
Create/update/delete SCM integrations	❌	✅
Create/update/delete LLM integrations	❌	✅
Admin Access
Grant access (share runner with groups)	❌	✅
Create runner tokens (for runner registration)	❌	✅
Access runner logs	❌	✅

Permission Inheritance

• Multiple groups: When a user belongs to multiple groups with access to the same resource, they receive the union of all permissions. The highest permission level applies.
• Organization admins: All org admins automatically have Admin permissions on all projects and runners, regardless of group memberships.

Best Practices

Organize Groups by Function

Create groups that reflect how your team works:

• By team: “Frontend Team,” “Backend Team,” “DevOps”
• By role: “Developers,” “Designers,” “Product Managers”
• By project: “Mobile App Team,” “API Team”

Use Descriptive Names and Descriptions

Help others understand what each group is for:

• ✅ “Backend Engineers - API and Database Development”
• ❌ “Group 1”

Start with Restrictive Access

Begin by sharing resources with specific groups. You can always expand access later:

1. Create groups for your teams
2. Share resources with relevant groups
3. Adjust permissions based on feedback
4. Expand to organization-wide access if needed

Review Access Regularly

Periodically review who has access to your resources:

• Check group memberships when people change roles
• Remove access for team members who no longer need it
• Update permission levels as responsibilities change

Consider Runner Dependencies

Before restricting runner access:

1. Identify which projects use the runner
2. Ensure all project users also have runner access
3. Communicate changes to affected teams

Use the Right Permission Level

Grant the minimum permissions needed:

• Most team members need User access
• Team leads or maintainers need Editor access
• Only a few people need Admin access

Review the detailed permissions in the “Roles and Permissions” section to understand what each role can do.

Frequently Asked Questions

Q: Can someone be in multiple groups?

Yes, team members can belong to multiple groups. They’ll receive the combined permissions from all their groups. If someone has User access through one group and Admin access through another, they effectively have Admin access.

Q: What happens when I delete a group?

All members lose access to resources that were shared exclusively with that group. Resources shared with other groups or with everyone in the organization remain accessible. The group deletion is permanent and cannot be undone.

Q: I can see a project but can’t create environments. Why?

This usually means you have access to the project but not to any of the runners it uses. Contact your organization admin to request runner access.

Q: I added someone to a group but they still can’t access a resource. What should I check?

Verify that the resource is shared with the group, the person has runner access if needed, they’ve refreshed their browser, and check for any error messages.

Q: I removed someone from a group but they still have access. Why?

They might be in another group with access, included in “Everyone in Organization” access, or they’re an organization administrator.

Q: I can’t create or edit groups. What do I need?

Creating and managing groups requires organization admin permissions. Contact your organization admin if you need to manage groups.

Q: After sharing a runner, team members still can’t use a project. What’s wrong?

Verify the project uses that runner, team members have project access, they’re in the shared group, and no policies are blocking access.

Q: Can I see who has access to a resource?

Yes, open the Share dialog for any resource to see which groups have access and their permission levels. You can then view those groups to see their members.

Q: What happens if I delete a runner that projects depend on?

Projects configured to use that runner will no longer be able to create environments using that runner’s environment classes. If the project has other environment classes from different runners, those will still work. If it was the only runner, the project becomes unusable until you configure it with a new runner.