Nuxt Studio supports authentication with GitHub, GitLab, and Google OAuth providers.
| Feature | GitHub OAuth | GitLab OAuth | Google OAuth |
|---|---|---|---|
| Authentication | ✅ | ✅ | ✅ |
| Git Operations | ✅ Direct | ✅ Direct | ⚠️ Requires Token |
| Access Control | OAuth scope | OAuth scope | Email whitelist |
| Moderator Whitelist | ✅ Optional | ✅ Optional | ⚠️ Required |
| Required Tokens | None (OAuth only) | None (OAuth only) | GitHub or GitLab Token |
To use GitHub as your authentication provider, you need to create a GitHub OAuth application.
Go to GitHub Developer Settings and click New OAuth App
Fill in the required fields:
https://yourdomain.comhttps://yourdomain.comhttp://localhost:3000/__nuxt_studio/auth/gitlabAfter creating the OAuth app, you'll receive:
Add the GitHub OAuth credentials to your deployment platform's environment variables or in your .env file in local
STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
# Optional: Comma-separated list of authorized email addresses for additional access control
# STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com
To use GitLab as your authentication provider, you need to create a GitLab OAuth application.
Go to your GitLab User Settings → Applications (or your group/organization settings) and create a New Application.
Fill in the required fields:
https://yourdomain.com/__nuxt_studio/auth/gitlabapi (required for publication)http://localhost:3000/__nuxt_studio/auth/gitlabAfter creating the OAuth application, you'll receive:
Add the GitLab OAuth credentials to your deployment platform's environment variables or in your .env file in local
STUDIO_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
STUDIO_GITLAB_CLIENT_SECRET=<your_gitlab_secret>
# Optional: Comma-separated list of authorized email addresses for additional access control
# STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com
To use Google as your authentication provider, you need to create a Google OAuth application.
Go to Google Cloud Console and select or create a project, then navigate to APIs & Services → Credentials.
Click Create Credentials and OAuth client ID and select Web application as the application type.
Fill in the required fields:
https://yourdomain.com/__nuxt_studio/auth/googlehttp://localhost:3000/__nuxt_studio/auth/googleAfter creating the OAuth client, you'll receive:
Create a Fine-grained GitHub Personal Access Token for your specific repository on GitHub Settings → Personal access tokens.
Fill in the required fields:
Create a GitLab Personal Access Token from User Settings → Personal access tokens (or your group/organization settings if applicable) on GitLab.
Recommended configuration:
api (required for reading/writing repository content)Copy the generated token; you won’t be able to see it again.
STUDIO_GITHUB_TOKEN or STUDIO_GITLAB_TOKEN) is required to push changes to your repository.Add the Google OAuth credentials and the Personal Access Token for your Git provider to your deployment platform's environment variables or in your .env file locally. Do not forget to also whitelist users allowed to connect with Google with the STUDIO_GITHUB_MODERATORS variable.
STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com
STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com
STUDIO_GOOGLE_MODERATORS environment variable is required and must contain a comma-separated list of email addresses that are allowed to access the Studio. Only users with these email addresses will be able to authenticate./_studio (or on the route you've configured) to start editing and publishing content.You can optionally restrict access to Studio by defining a whitelist of authorized users through the STUDIO_{PROVIDER}_MODERATORS environment variable. This works with all OAuth providers (GitHub, GitLab, and Google).
STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com,content-manager@example.com
STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com,content-manager@example.com
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com,content-manager@example.com
The moderator list should be a comma-separated list of email addresses. Only users who sign in with accounts matching these email addresses will be granted access to the Studio.
STUDIO_{PROVIDER}_MODERATORS is not set or empty, all users who can authenticate through your OAuth app will have access to Studio. The whitelist is optional. The Oauth scope will be used for write access preventing any non allowed user to push changes to your repository.STUDIO_GOOGLE_MODERATORS environment variable is required. Without it, no one will be able to access Studio when using Google OAuth.By default, Studio uses your deployment URL as the OAuth redirect URL. If you need to customize it you can specify a custom redirect URL:
# Using GitHub provider
STUDIO_GITHUB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/github
# Using GitLab provider
STUDIO_GITLAB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/gitlab
# Using Google provider
STUDIO_GOOGLE_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/google
By default, Studio commits changes to the branch specified in your configuration (typically main). However, you can configure Studio to work with a staging or preview branch instead.
This is useful when you want to review changes on a preview environment before merging to production. You can currently handle pull requests manually from GitHub, but automatic PR creation is included in our roadmap and will be implemented in a future release.
Update your nuxt.config.ts to target your staging branch.
export default defineNuxtConfig({
studio: {
repository: {
owner: 'your-username',
repo: 'your-repo',
branch: PROCESS.ENV.STUDIO_BRANCH_NAME, // Target your staging branch instead of main
}
}
})
Configure your hosting platform to deploy the staging branch to a preview URL (e.g., staging.yourdomain.com).
Create a new OAuth App specifically for your staging environment and use your staging URL as callback URL.
Configure your staging deployment env varibales with the staging OAuth credentials.
STUDIO_GITHUB_CLIENT_ID=<your_staging_github_client_id>
STUDIO_GITHUB_CLIENT_SECRET=<your_staging_github_client_secret>
STUDIO_GITHUB_BRANCH_NAME=<your_staging_branch_name>
Navigate to https://staging.yourdomain.com/_studio to edit content. All commits will be pushed to your configured staging branch.
Once you're satisfied with changes on your staging branch, create a pull request from your staging branch to your main branch on GitHub to deploy to production.