Skip to content

System Sync (Best Practices)

This page captures best practices/recommendations when using GitOps System Sync.

PR based approvals

Use the exact same process already in use to merge code using "pull or merge" requests when implementing Git to System Sync.

Repository configuration

Ensure that the 'repository, branch and folder path' tuple configuration is unique across pipelines. This will prevent issues such as artifacts getting overwritten in Git (resulting in resources getting deleted) on a 'System to Git' Sync.

Two way sync

If GitOps is the preferred interface of choice and 2 way sync needs to be enabled: - Restrict changes via other interfaces (e.g. UI) to an absolute bare minimum (e.g. only to be done by Org Admins under rare circumstances). This will prevent 'race condition' type scenarios leading to unpredictable behavior - Evaluate providing end users read only roles with Org Admins creating System Sync pipelines on behalf of end users

Back up

If two way sync is enabled and the intent of System to Git sync is only to back up artifacts, use a different 'repository, branch and folder path' tuple configuration for Destination Repository.

Structured folders

  • Use structured folders to drive 'Git to System' operations
  • On a 'System to Git' sync, write back always follows a 'structured folder' approach irrespective of how artifacts are maintained in Git. Not using a structured folder approach may lead to issues such as resources getting inadvertently deleted

Sharing Pipelines

  • Avoid sharing of pipelines across projects. Any Git to System sync operation as an example considers/reconciles all artifacts in the specified repository configuration and not just the artifact change that initiated the webhook trigger. This is to ensure that any 'missed triggers' don't lead to Git and the System states being out of sync
  • Not sharing pipelines across projects reduces the scope of reconciliation (and the resulting changes) to resources within the project on a Git to System Sync or System to Git Sync operation

Creation of Pipelines

It is recommend that Org Admins use 'system user' accounts when they are creating pipelines on behalf of end users.

Agents

It is recommended that at least two agents be specified in the Repository configuration. This ensures that System Sync operations are not disrupted in case one of the agents is down or unhealthy.