Git Promotion Workflow

Git Promotion is an advanced deployment setup that leverages Git Sync technology to deploy changes from one workspace to another, including across different Orvanta instances. The workflow combines staging and production environments with automated pull request creation.

How it works

The typical setup involves:

• Two workspaces (staging and prod) connected to their respective Git repositories via Git Sync
• The staging workspace configured to target the production repository for promotion
• When changes are deployed in staging, a branch named wm_deploy/[workspace]/[path] is created in the production repository
• A GitHub Action automatically creates a pull request
• Upon merge, Git Sync synchronizes the changes into the production workspace

Note that prod-repo and staging-repo can be (and often are) the same repo but targeting a different branch.

Prerequisites

This feature requires Git Sync, which is available only in Cloud plans and Self-Hosted Enterprise Edition.

Setup steps

1. Configure Git Sync

Set up Git Sync on both staging and production workspaces, optionally using different repositories or branches. Include CI/CD actions for bidirectional synchronization.

2. Set promotion target

In the staging workspace’s Git Sync settings, configure a promotion target pointing to the production branch. Choose between:

• Create one branch per deployed object (default)
• Group deployed objects by folder

3. GitHub Actions configuration

Add an additional workflow file to automatically create pull requests when wm_deploy/* branches are pushed:

name: "Git Promotion: Deploy from staging to prod"
on:
  push:
    branches:
      - wm_deploy/**
env:
  TARGET_BRANCH: prod
jobs:
  submit_pull_requests:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Create pull request
        run: |
          gh pr view ${{ github.ref_name }} \
          && gh pr reopen ${{ github.ref_name }} \
          || gh pr create -B ${{ env.TARGET_BRANCH }} -H ${{ github.ref_name }} \
          --title "${{github.event.head_commit.message }}" \
          --body "PR created by Github action '${{ github.workflow }}'"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

4. Testing

1. Create and deploy a script in staging within allowed path filters
2. Verify a pull request was created on GitHub
3. Merge the PR and confirm the script appears in the production workspace

Troubleshooting

Check the runs page with the “Sync” filter for Git sync job logs. Review GitHub action execution history for errors.

Managing multiple teams

Option 1: Same workspace, different folders, different repositories

Keep teams in one workspace with separate folders and repositories. Use orvanta.yaml includes to specify folder ownership:

includes:
  - "f/team1_folder/**"
  - "f/team2_folder/**"

This approach prevents overlapping changes while maintaining a unified workspace structure.

Option 2: Separate workspaces

Create isolated workspaces per team for complete separation, though this requires more maintenance.

Pull request management

Changes to the same item will be grouped into a single PR. Different items will create separate PRs. Use the folder grouping option to organize by folder instead of individual items.