Adding and Removing Users in Netlify CMS / Decap CMS

Netlify CMS (now Decap CMS) uses Git-based authentication, meaning user management depends on your Git provider (GitHub, GitLab, Bitbucket) and authentication backend. This guide covers user management across different configurations.

Understanding Netlify CMS User Management

Git-Based Access Control

Unlike traditional CMSs with database users, Netlify CMS grants access based on Git repository permissions:

Repository Access = CMS Access

• GitHub Repository Collaborators → Can access Netlify CMS
• GitLab Project Members → Can access Netlify CMS
• Bitbucket Workspace Members → Can access Netlify CMS

Authentication Backends

Netlify CMS supports multiple authentication methods:

1. Git Gateway (Netlify Identity)

• Managed by Netlify
• User registration/invitation via Netlify UI
• No direct Git access required
• Best for non-technical editors

2. GitHub OAuth

• Direct GitHub authentication
• Requires GitHub repository access
• Best for developer teams

3. GitLab OAuth

• Direct GitLab authentication
• Requires GitLab project access

4. Bitbucket OAuth

• Direct Bitbucket authentication
• Requires Bitbucket repository access

Method 1: Git Gateway (Netlify Identity)

Best for: Non-technical editors, clients, content teams without Git knowledge

Adding Users via Git Gateway

Step 1: Enable Netlify Identity

1. Netlify Dashboard → Select site
2. Identity tab
3. Click Enable Identity

Step 2: Configure Registration Settings

Identity → Settings and usage

Registration preferences:
- Open: Anyone can sign up (not recommended)
- Invite only: Only invited users (recommended)

Step 3: Invite Users

Via Netlify UI:

1. Identity → Invite users
2. Enter email address
3. Click Send
4. User receives invitation email
5. User clicks link to set password
6. User can now access /admin on your site

Invite Multiple Users:

1. Click "Invite users"
2. Enter multiple emails (comma-separated)
3. Send invitations

Step 4: Configure CMS

Ensure config.yml uses Git Gateway backend:

# static/admin/config.yml
backend:
  name: git-gateway
  branch: main

# Enable editorial workflow (optional)
publish_mode: editorial_workflow

Removing Users via Git Gateway

Option 1: Delete User (Permanent)

1. Netlify Dashboard → Identity
2. Find user
3. Click ... → Delete user
4. Confirm deletion
5. User immediately loses access

Option 2: Disable User (Temporary)

1. Identity → Find user
2. Click user email
3. Actions → Suspend user
4. User cannot log in (can be re-enabled)

Managing User Roles (Git Gateway)

Git Gateway doesn't have built-in roles. Access control via:

1. Editorial Workflow

Enable draft/review/publish workflow:

# config.yml
publish_mode: editorial_workflow

Workflow stages:

• Draft - Content creator saves work
• In Review - Ready for review
• Ready - Approved, ready to publish
• Published - Merged to main branch

All users can create drafts, but publishing still requires Git repository permissions.

2. Repository Permissions

Control who can approve pull requests:

1. GitHub → Repository → Settings → Branches
2. Select main branch
3. Enable "Require pull request reviews before merging"
4. Editors can create PRs, but admins must approve

Method 2: GitHub OAuth

Best for: Developer teams, technical users familiar with Git

Adding Users via GitHub OAuth

Step 1: Configure GitHub OAuth Backend

# static/admin/config.yml
backend:
  name: github
  repo: your-username/your-repo
  branch: main

Step 2: Add Users to GitHub Repository

1. GitHub → Your repository
2. Settings → Collaborators
3. Click Add people
4. Enter GitHub username or email
5. Select role:
   • Read - Can view, clone (no CMS access for editing)
   • Write - Can create branches, edit (CMS access)
   • Admin - Full control

Step 3: User Authentication

1. User visits yoursite.com/admin
2. Clicks "Login with GitHub"
3. Authorizes Netlify CMS OAuth app
4. Redirected to CMS interface

Removing Users via GitHub OAuth

1. GitHub → Repository → Settings → Collaborators
2. Find user
3. Click Remove
4. User immediately loses CMS access

Repository Permission Levels

Read:

• Can view repository
• Can clone repository
• Cannot edit via CMS

Write:

• Can create branches
• Can commit changes
• Can edit via CMS
• Can create pull requests

Admin:

• Full repository access
• Can merge pull requests
• Can change repository settings
• Full CMS access

Method 3: GitLab OAuth

Best for: Teams using GitLab for version control

Adding Users via GitLab OAuth

Step 1: Configure GitLab Backend

# static/admin/config.yml
backend:
  name: gitlab
  repo: your-username/your-repo
  branch: main

Step 2: Add Users to GitLab Project

1. GitLab → Your project
2. Members
3. Click Invite members
4. Enter username or email
5. Select role:
   • Guest - No CMS access
   • Reporter - Read-only
   • Developer - Can edit via CMS
   • Maintainer - Can merge, full CMS access
   • Owner - Full control

Removing Users via GitLab

1. GitLab → Project → Members
2. Find user
3. Click Remove member
4. Confirm removal

Method 4: Bitbucket OAuth

Best for: Teams using Bitbucket

Adding Users via Bitbucket

Step 1: Configure Bitbucket Backend

# static/admin/config.yml
backend:
  name: bitbucket
  repo: your-username/your-repo
  branch: main

Step 2: Add Users to Workspace

1. Bitbucket → Workspace
2. Workspace settings → Users and groups
3. Invite user
4. Assign permission:
   • Read - No write access
   • Write - Can edit via CMS
   • Admin - Full access

Removing Users via Bitbucket

1. Workspace settings → Users
2. Find user
3. Remove from workspace

Editorial Workflow for Access Control

Enable Editorial Workflow

# static/admin/config.yml
publish_mode: editorial_workflow

# Optional: Require approval
backend:
  name: github  # or gitlab
  repo: your-repo
  branch: main
  squash_merges: true

Workflow Process

1. Draft Stage

• Any user with Write access can create drafts
• Saved as entry in CMS, no Git commit yet

2. In Review Stage

• User moves draft to "In Review"
• Creates Git branch and pull request
• Other users can review via GitHub/GitLab

3. Ready Stage

• Approved by reviewer
• Marked as ready to publish

4. Published

• Merged to main branch
• Triggers Netlify build
• Content goes live

Configure Branch Protection

GitHub:

Settings → Branches → Branch protection rules → Add rule

Branch name: main

☑ Require pull request reviews before merging
  Required approvals: 1

☑ Require status checks to pass before merging

☑ Include administrators (enforce for everyone)

GitLab:

Settings → Repository → Protected Branches

Branch: main
Allowed to merge: Maintainers
Allowed to push: No one

Bulk User Management

Import Users (Git Gateway)

Netlify CLI:

# Install Netlify CLI
npm install -g netlify-cli

# Login
netlify login

# Link to site
netlify link

# Invite users from CSV
netlify identity:invite email1@example.com email2@example.com email3@example.com

CSV Format:

email
user1@example.com
user2@example.com
user3@example.com

Batch Invite Script

// invite-users.js
const fetch = require('node-fetch');

const siteId = 'YOUR_SITE_ID';
const token = 'YOUR_NETLIFY_TOKEN';
const emails = [
  'user1@example.com',
  'user2@example.com',
  'user3@example.com'
];

async function inviteUser(email) {
  const response = await fetch(`https://api.netlify.com/api/v1/sites/${siteId}/identity/users`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  return response.json();
}

emails.forEach(async (email) => {
  const result = await inviteUser(email);
  console.log(`Invited ${email}:`, result);
});

Security Best Practices

1. Principle of Least Privilege

Don't give Admin access unless needed:

• Content creators: Write/Developer access
• Reviewers: Write/Developer access + review permissions
• Administrators: Admin access only when necessary

2. Enable Two-Factor Authentication

GitHub:

Settings → Password and authentication → Two-factor authentication
Enable 2FA

GitLab:

User Settings → Account → Two-Factor Authentication
Enable 2FA

Netlify Identity:

Currently not supported (use GitHub/GitLab OAuth for 2FA)

3. Audit User Access

GitHub:

Repository → Insights → Traffic → Collaborators
Review who has access

Netlify Identity:

Netlify Dashboard → Identity → Users
Review active users

4. Remove Inactive Users

Regular audit schedule:

• Monthly: Review user list
• Quarterly: Remove inactive users
• On offboarding: Immediate removal

Troubleshooting

User Can't Log In (Git Gateway)

Symptom: User receives invitation but can't access CMS.

Checklist:

• Identity enabled on Netlify site
• User confirmed email
• User set password
• config.yml has backend: git-gateway
• User visiting correct domain (not preview URL)

Fix:

1. Netlify → Identity → User
2. Resend invitation
3. Verify email confirmation

User Can Log In But Can't Edit

Symptom: User authenticated but gets "Cannot edit" error.

Causes:

• GitHub: User has Read access (needs Write)
• GitLab: User is Reporter (needs Developer)
• Branch protection: User can't push to protected branch

Fix:

1. Increase repository permission level
2. Or enable editorial workflow (creates PRs instead)

Too Many Users

Netlify Identity Limits:

• Free tier: 1,000 active users
• Paid tier: 5,000+ users

Exceeded limit:

• Upgrade Netlify plan
• Switch to GitHub/GitLab OAuth (no user limits)

Next Steps

• Configure Roles and Permissions - Fine-tune access control
• Set Up Editorial Workflow - Draft/review/publish process

Related Resources

• Netlify Identity Documentation
• Netlify CMS Authentication
• GitHub Permissions
• GitLab Permissions