Studio

Oauth Providers

Configure OAuth providers and synchronizes content between your production website and your Git repository.
After initial OAuth setup, synchronization happens automatically and requires no manual action.

OAuth Providers

Nuxt Studio supports authentication with GitHub, GitLab, and Google OAuth providers.

Provider Comparison

FeatureGitHub OAuthGitLab OAuthGoogle OAuth
Authentication✅✅✅
Git Operations✅ Direct✅ Direct⚠️ Requires Token
Access ControlOAuth scopeOAuth scopeEmail whitelist
Moderator Whitelist✅ Optional✅ Optional⚠️ Required
Required TokensNone (OAuth only)None (OAuth only)GitHub or GitLab Token
You can use both Google and another Git provider for the same application. Google is usually used for non-technical users who don't want to create a GitHub or GitLab account.

GitHub

To use GitHub as your authentication provider, you need to create a GitHub OAuth application.

Navigate to GitHub Developer Settings

Go to GitHub Developer Settings and click New OAuth App

Configure the GitHub OAuth Application

Fill in the required fields:

  • Application name: Your app name
  • Homepage URL: https://yourdomain.com
  • Authorization callback URL: https://yourdomain.com
If you want to try studio locally, add your local url as redirect URI: http://localhost:3000/__nuxt_studio/auth/gitlab

Copy Your GitHub Credentials

After creating the OAuth app, you'll receive:

  • A Client ID (visible immediately)
  • A Client Secret (click Generate a new client secret)

Set your GitHub environment Variables

Add the GitHub OAuth credentials to your deployment platform's environment variables or in your .env file in local

.env
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

GitLab

To use GitLab as your authentication provider, you need to create a GitLab OAuth application.

Navigate to GitLab Applications

Go to your GitLab User Settings → Applications (or your group/organization settings) and create a New Application.

Configure the GitLab OAuth Application

Fill in the required fields:

  • Application name: Your app name
  • Redirect URI: https://yourdomain.com/__nuxt_studio/auth/gitlab
  • Scopes: Select api (required for publication)
If you want to try studio locally, add your local url as redirect URI: http://localhost:3000/__nuxt_studio/auth/gitlab

Copy Your GitLab Credentials

After creating the OAuth application, you'll receive:

  • An Application ID (visible immediately)
  • A Secret (visible immediately)

Set your GitLab environment Variables

Add the GitLab OAuth credentials to your deployment platform's environment variables or in your .env file in local

.env
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

Google

To use Google as your authentication provider, you need to create a Google OAuth application.

Navigate to Google Cloud Console

Go to Google Cloud Console and select or create a project, then navigate to APIs & Services → Credentials.

Create OAuth Application

Click Create Credentials and OAuth client ID and select Web application as the application type.

Fill in the required fields:

  • Name: Your app name
  • Authorized redirect URIs: https://yourdomain.com/__nuxt_studio/auth/google
If you want to try studio locally, add your local url as redirect URI: http://localhost:3000/__nuxt_studio/auth/google

After creating the OAuth client, you'll receive:

  • A Client ID
  • A Client Secret
Do not forget to save them.

Create a Personal Access Token

Create a Fine-grained GitHub Personal Access Token for your specific repository on GitHub Settings → Personal access tokens.

Fill in the required fields:

  • Token name: Your app name
  • Resource owner: The GitHub organization (or user) the repository belongs to
  • Repository access: Select Only select repositories and choose your repository
  • Permissions: Click Add permission and select Contents then update access to Read and write
Google OAuth is used for authentication only. The Git Personal Access Token (STUDIO_GITHUB_TOKEN or STUDIO_GITLAB_TOKEN) is required to push changes to your repository.

Set your Google environment Variables

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.

.env.github
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
The 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.
That's it! Once deployed with the appropriate credentials set as environment variables. Studio will be accessible from your production instance. Just login on the /_studio (or on the route you've configured) to start editing and publishing content.

Advanced options

Access Control with Moderators

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).

Moderators are required for Google OAuth and optional for GitHub or GitLab.
.env
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.

Behavior by Provider

  • GitHub & GitLab: If 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.
  • Google OAuth: The STUDIO_GOOGLE_MODERATORS environment variable is required. Without it, no one will be able to access Studio when using Google OAuth.

Custom Redirect URL

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:

.env
# 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
This is useful when you need to handle OAuth callbacks through a specific endpoint.

Working with Staging/Preview Branches

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.

Configure

Update your nuxt.config.ts to target your staging branch.

You can use environment variables to manage multiple branches for different environments.
nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    repository: {
      owner: 'your-username',
      repo: 'your-repo',
      branch: PROCESS.ENV.STUDIO_BRANCH_NAME, // Target your staging branch instead of main
    }
  }
})

Deploy

Configure your hosting platform to deploy the staging branch to a preview URL (e.g., staging.yourdomain.com).

Create a Separate OAuth App (based on your Git provider)

Create a new OAuth App specifically for your staging environment and use your staging URL as callback URL.

Set Environment Variables

Configure your staging deployment env varibales with the staging OAuth credentials.

.env.staging
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>

Access Studio on Staging

Navigate to https://staging.yourdomain.com/_studio to edit content. All commits will be pushed to your configured staging branch.

Merging to Production

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.

Pull Request Automation Coming Soon
Automatic pull request creation from Studio is planned for a future release. For now, you'll need to manually create PRs on GitHub to merge staging changes into your main branch.

Setup

Learn how to install and configure Nuxt Studio to edit your content in production with GitHub authentication.

Content Editors

Discover and select your favorite way to manage your content between the visual or the code editor.