docs(studio): working with staging

Author: larbish

docs/content/docs/9.studio/2.setup.md

@@ -129,6 +129,72 @@ export default defineNuxtConfig({
 })
 ```
 
+## 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.
+
+::prose-steps
+### Configure
+
+Update your `nuxt.config.ts` to target your staging branch.
+
+  :::tip
+  You can use environment variables to manage multiple branches for different environments.
+  :::
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  studio: {
+    repository: {
+      owner: 'your-username',
+      repo: 'your-repo',
+      branch: PROCESS.ENV.STUDIO_GITHUB_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 GitHub OAuth App
+
+Create a new OAuth App specifically for your staging environment:
+
+- **Application name**: Your App Name (Staging)
+- **Homepage URL**: `https://staging.yourdomain.com`
+- **Authorization callback URL**: `https://staging.yourdomain.com`
+
+### Set Environment Variables
+
+Configure your staging deployment with the staging OAuth credentials and your br
+
+```bash [.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.
+
+  :::note
+  **Pull Request Automation Coming Soon**
+  
+  :br
+  
+  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.
+  :::
+::
+
 ### Accessing Studio
 
 After deployment, access the Studio interface by navigating to your configured route (default: `/_studio`):