---
title: "Git Providers"
description: "Configure Git providers to synchronize content between your production website and your Git repository."
canonical_url: "https://nuxt.studio/git-providers"
---
# 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.

<note to="https://nuxt.studio/auth-providers">

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.

</note>

## 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](https://nuxt.studio/auth-providers), the OAuth token obtained during authentication is automatically used for Git operations. No additional configuration is needed.

```bash [.env]
# GitHub OAuth - token is obtained automatically during login
NUXT_STUDIO_AUTH_GITHUB_CLIENT_ID=<your_github_client_id>
NUXT_STUDIO_AUTH_GITHUB_CLIENT_SECRET=<your_github_client_secret>

# Or GitLab OAuth - token is obtained automatically during login
NUXT_STUDIO_AUTH_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
NUXT_STUDIO_AUTH_GITLAB_APPLICATION_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:

```bash [.env]
# For GitHub repositories
NUXT_STUDIO_GIT_GITHUB_TOKEN=<your_github_personal_access_token>

# For GitLab repositories
NUXT_STUDIO_GIT_GITLAB_TOKEN=<your_gitlab_personal_access_token>
```

<tip>

Check the section below to have more info about how to create a PAT for GitHub or GitLab provider.

</tip>

## Automatic Detection

When deploying on **Vercel**, **Netlify**, **GitHub Actions**, or **GitLab CI**, Studio automatically detects the repository `provider`, `owner`, `repo`, and `branch` from the platform's environment variables.

This means you can skip the `studio.repository` configuration entirely on these platforms — just set up your [Auth provider](https://nuxt.studio/auth-providers) and deploy.

<note>

Auto-detection applies to all fields, including `branch`. CI-detected values take precedence over manually configured values in `nuxt.config.ts`. To use a specific branch, unset the corresponding CI environment variable (e.g. `GITHUB_REF_NAME`) or configure your deployment platform accordingly.

</note>

<warning>

On Vercel, you must enable **Automatically expose System Environment Variables** in your project settings (**Settings → Environment Variables**) for auto-detection to work.

</warning>

## Supported Providers

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

### GitHub

When deploying on Vercel or Netlify with a GitHub repository, the configuration below is automatically detected. You can also configure it manually in `nuxt.config.ts`:

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

<warning>

This section is required if you're using an [Auth provider](https://nuxt.studio/auth-providers) 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.

</warning>

<steps level="4">

#### Navigate to GitHub Token Settings

Go to [GitHub Settings → Personal access tokens](https://github.com/settings/personal-access-tokens/new) 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:

```bash [.env]
NUXT_STUDIO_GIT_GITHUB_TOKEN=<your_github_personal_access_token>
```

</steps>

### GitLab

When deploying on GitLab CI, the configuration below is automatically detected. You can also configure it manually in `nuxt.config.ts`:

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

<note>

**Self hosted GitLab**:

- You can use the `NUXT_STUDIO_AUTH_GITLAB_INSTANCE_URL` to override the default GitLab instance URL if you're using a self-hosted instance.
- [Oauth instance URL](https://nuxt.studio/auth-providers#set-gitlab-environment-variables) is based on the same env variable by default.

</note>

#### Creating a GitLab Personal Access Token

<warning>

This section is required if you're using an [Auth provider](https://nuxt.studio/auth-providers) 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.

</warning>

<steps level="4">

#### 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](https://docs.gitlab.com/user/profile/personal_access_tokens/).
- **Scopes**: `api` (required for reading/writing repository content) <warning>

Copy the generated token immediately; you won't be able to see it again.

</warning>

#### Set GitLab Environment Variable

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

```bash [.env]
NUXT_STUDIO_GIT_GITLAB_TOKEN=<your_gitlab_personal_access_token>
```

</steps>

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

<steps>

### Configure Your Branch

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

<tip>

Set `NUXT_PUBLIC_STUDIO_REPOSITORY_BRANCH` at deployment time to configure the branch per environment without rebuilding.

</tip>

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  studio: {
    repository: {
      owner: 'your-username',
      repo: 'your-repo',
      branch: 'main' // override at runtime via NUXT_PUBLIC_STUDIO_REPOSITORY_BRANCH
    }
  }
})
```

### 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](https://nuxt.studio/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.

</steps>


## Sitemap

See the full [sitemap](https://nuxt.studio/sitemap.md) for all pages.