Git Sync

With Git sync, every policy change goes through a pull request in your own GitHub or GitLab repository. Sync runs both ways: a change merged in the repository applies here, and a change made here opens a pull request (a merge request on GitLab) instead of saving.

Set Up Git Sync

1. Go to Settings → Guardrails and click Set up Git sync. After the APPA Keeper saves a policy, the banner in chat links here too.
2. Pick GitHub or GitLab, then follow its steps below.

When setup is done, the card on Settings → Guardrails shows Connected.

GitHub

1. Enter the GitHub URL, either GitHub.com or your GitHub Enterprise Server address, and the Organization. Then choose one:
   • Start fresh: click Create on GitHub to create a private repository from the OpenAPPA template. On GitHub Enterprise Server, create an empty private repository instead, and setup adds the OpenAPPA files.
   • Use an existing repository: one that already holds an OpenAPPA policy.
2. Pick a GitHub App: Use an App I already have, or Create a new GitHub App, which creates one on GitHub with no keys to copy. Install it on the policy repository only.
3. Choose the repository and click Connect repository. To change the Branch, Policy file (appa.toml), Validations folder (traces), or Sync schedule, open Advanced first.

The App needs Read & write on Contents and Pull requests, and on Workflows too on GitHub Enterprise Server. If repository rules block the first commit, setup opens a pull request instead, and your current policy stays active until it merges. Click Review and merge, and merge it once its checks pass.

GitLab

Git sync works with gitlab.com and self-managed GitLab, through an access token with the api scope.

1. Pick a saved token, or click Add a GitLab token.
2. Choose the policy project. To change the branch, policy file, validations folder, or schedule, open Advanced first.
   • New project: pick a Group, or Your namespace for your own account, and enter a Project name. Click Create project. Setup creates a private project with your current policy.
   • Existing project: pick it and click Connect project.

If GitLab refuses the first commit to a protected branch, setup stops with an error. Use a token with the Maintainer role, or allow the first push to that branch.

Repository Checks

Before you connect, the dialog checks what the repository holds:

• OpenAPPA template, Empty repository, or Empty project: setup copies your current policy into it.
• Found appa.toml: that file replaces your current policy.
• No appa.toml: pick another repository, or set the policy file under Advanced.
• No access: the App or token cannot read it. On GitHub, click Change access to fix it.

Validations in Git

With Git sync on, validation files live in the repository's validations folder, and Archestra loads them from the same commit as the policy. Change the folder with Edit source on Settings → Guardrails. An edit in Archestra stays a draft until you commit it to the repository.

What to know:

• Credentials never live in the repository. A policy with a [credentials] line fails to sync. Bind keys on the Batteries tab instead.
• Validation failures do not block a merge on their own. Set up repository CI if they should.

Required permissions:

• organizationSettings:update to set up Git sync.
• credential:read to pick a saved GitHub App or GitLab token.
• credential:create to create a GitHub App or save a GitLab token.