Why You Should Separate the developers Team from the publish Team in npm Organizations ― A Practical Pattern for Clear Collaborators in Enterprise Settings

When managing packages in an npm Organization, it’s important to understand the characteristics of the developers team. Especially in enterprise settings, if you don’t properly separate IT administrators from developers, unintended members will appear in the package’s Collaborators list.

What is the developers Team?

According to the npm official documentation, the developers team has the following characteristics:

Automatic Creation and Addition

It is automatically created when you create an Organization
Members added to the Organization are automatically added to the developers team
Organization owners are no exception

Default Access Rights

Has read/write access to all newly created packages

Cannot Be Deleted

The official documentation clearly states:

Note: You cannot remove the developers team.

The reasons it cannot be deleted are:

It functions as the Source of Truth for all users, packages, and default permissions within the Organization
When you want to restrict write access, it’s better to set the default permissions to read-only and create separate teams for managing write permissions

Problems in Enterprise Operations

When operating an npm Organization in an enterprise setting, you often end up with a structure like this:

@your-company (Organization)
├── IT Administrators (Organization Owner/Admin)
├── Development Team A (develops Package A)
├── Development Team B (develops Package B)
└── Other Members (only use packages)

The automatic addition to the developers team causes the following problems:

The developers Team Appears in Collaborators

The npm package page displays Collaborators. When the developers team has access to a package, the “developers team” is shown as Collaborators, making it difficult to identify who the actual developers are.

Since IT administrators and members of other teams who aren’t involved in the package development are also included in the developers team, ownership becomes unclear.

Solution: Separating the publish Team

To solve this problem, create a separate publish team and remove the developers team’s access to the package.

1. Change the developers Team’s Package Permissions to read-only

Change the developers team’s permissions for the target package to read-only.

# Change permissions per package via CLI
npm access grant read-only @your-company:developers @your-company/your-package

Note: This operation is a per-package setting. Organization-wide default settings are configured through the Web UI.

2. Create a publish Team

Create a publish team for each package or project.

# Create the team
npm team create @your-company:package-a-publishers
 
# Add members
npm team add @your-company:package-a-publishers developer1
npm team add @your-company:package-a-publishers developer2

3. Grant write Permission to the publish Team

npm access grant read-write @your-company:package-a-publishers @your-company/package-a

4. Restrict the developers Team’s write Permission

If you’ve already changed to read-only in step 1, this step is unnecessary.

If you want to completely remove access, use the following command, but be careful with private packages.

npm access revoke @your-company:developers @your-company/package-a

Note: If you completely revoke permissions from developers for a private package, members of the developers team won’t even be able to install the package. In most cases, maintaining read-only access rather than revoking is safer.

Note: Handling New Package Creation

When you npm publish a new package, write permission is granted to the developers team by default. Therefore, you need to execute steps 1-3 above every time you create a new package.

Incorporating this into your CI/CD pipeline or including it in a package creation checklist can help prevent missed configurations.

Operational Example

We recommend the following team structure:

@your-company (Organization)
├── developers (default, all members, read-only)
├── package-a-publishers (only Package A developers)
├── package-b-publishers (only Package B developers)
└── admins (IT administrators, for Organization management)

This structure achieves the following:

Only actual developers appear in Collaborators
IT administrators focus solely on Organization management
Clear responsibility scope for each package

Reference: Similar Concepts

Principle of Least Privilege

This operational approach is based on the security fundamental “Principle of Least Privilege.” The OWASP npm Security Cheat Sheet also recommends the following as a best practice for supply chain protection:

Restrict, scope and rotate CI and publisher tokens. Bind publisher tokens to workflows or IP ranges and minimize privileges.

Trusted Publishing

When integrating with GitHub Actions or GitLab CI/CD, consider using Trusted Publishing. It allows you to publish directly from CI/CD workflows without using long-lived tokens.

Integration with GitHub Organizations

Many enterprises connect GitHub Organizations and npm Organizations via SSO. In this case, you can sync GitHub’s team structure to npm.

When using GitHub integration, you can reduce team management overhead by managing teams on the GitHub side and auto-syncing to npm. However, the developers team’s behavior remains unchanged, so the permission separation explained in this article is still necessary.

Similar Feature in GitHub Packages

GitHub Packages also offers similar permission management.

Organizations can disable automatic inheritance of access permissions for all new packages scoped to their organization.

You can choose whether to automatically inherit repository permissions or configure them individually per package.

Summary

The developers team in npm Organizations is a convenient feature, but enterprise operations require attention to the following points:

The developers team cannot be deleted - This is by design
All members are automatically added - Including IT administrators
Everyone appears in Collaborators - Including non-developers

As a solution, by creating a separate publish team and restricting the developers team’s access to read-only, you can display only the actual development members in the package’s Collaborators.

This operational approach follows the Principle of Least Privilege and is a recommended approach from a security perspective.

That’s all from the Gemba on separating the developers team and publish team in npm Organizations.