Studio

Git Providers

Configure Git providers to synchronize content between your production website and your Git repository.

Git providers handle the synchronization between Studio and your repository. They are responsible for pushing content changes (commits) to your Git repository when you publish from Studio.

Git providers are distinct from Auth providers. Git providers determine where your repository is hosted and enable you to publish content changes, while Auth providers control how users authenticate and gain access to Studio.

Supported Providers

Studio supports two Git providers for repository operations: GitHub and GitLab.

GitHub

To use GitHub as your Git provider, configure your repository settings in nuxt.config.ts:

nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    repository: {
      provider: 'github',
      owner: 'your-username',
      repo: 'your-repo',
      branch: 'main' // Optional, defaults to 'main'
    }
  }
})

Creating a GitHub Personal Access Token

This section is required if you're using an Auth provider that doesn't provide Git access (like Google OAuth or Custom Auth). In this case you'll need to create a Personal Access Token to publish your changes.

Navigate to GitHub Token Settings

Go to GitHub Settings → Personal access tokens and create a new Fine-grained Personal Access Token.

Configure the GitHub Token

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

Set GitHub Environment Variable

Add the token to your deployment platform's environment variables:

.env
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>

GitLab

To use GitLab as your Git provider, configure your repository settings in nuxt.config.ts:

nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    repository: {
      owner: 'your-username', // or group name
      repo: 'your-repo',
      branch: 'main' // Optional, defaults to 'main'
    }
  }
})

Creating a GitLab Personal Access Token

This section is required if you're using an Auth provider that doesn't provide Git access (like Google OAuth or Custom Auth). In this case you'll need to create a Personal Access Token to publish your changes.

Navigate to GitLab Token Settings

Go to User Settings → Personal access tokens (or your group/organization settings if applicable) on GitLab.

Configure the GitLab Token

Fill in the required fields:

  • Name: Your app name
  • Expiration date: Set according to your security policy (GitLab defaults to 365 days, and non-expiring tokens are not allowed on most instances). See GitLab's guidance on expiry limits.
  • Scopes: api (required for reading/writing repository content)
    Copy the generated token immediately; you won't be able to see it again.

Set GitLab Environment Variable

Add the token to your deployment platform's environment variables:

.env
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>

Publication Requirements

To publish content changes to your repository, Studio needs a valid access token with write permissions. The token can come from two sources:

OAuth-based Access (Automatic)

When using GitHub OAuth or GitLab OAuth as your Auth provider, the OAuth token obtained during authentication is automatically used for Git operations. No additional configuration is needed.

.env
# GitHub OAuth - token is obtained automatically during login
STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>

# Or GitLab OAuth - token is obtained automatically during login
STUDIO_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
STUDIO_GITLAB_CLIENT_SECRET=<your_gitlab_secret>

Personal Access Token (Manual)

When using Google OAuth or Custom Auth as your Auth provider, you must provide a Personal Access Token (PAT) with repository write permissions:

.env
# For GitHub repositories
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>

# For GitLab repositories
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>
The Personal Access Token must have write permissions to the repository. Without it, users authenticated via Google OAuth or Custom Auth won't be able to publish changes.

Working with 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.

Configure Your Branch

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 || 'main'
    }
  }
})

Deploy Your Staging Environment

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

Configure Auth Provider for Staging

Create a new OAuth App specifically for your staging environment with your staging URL as callback URL. See Auth Providers for setup instructions.

Set Environment Variables

Configure your staging deployment environment variables depending on the Git and Auth provider you are using.

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

Auth Providers

Configure authentication providers to control access to Nuxt Studio.