Skip to main content
pgw config sync applies a plan that only creates and updates without asking. Without a terminal, a plan that deletes needs --yes, so an unattended run can’t delete anything unless you pass that flag.

Before you begin

  • A tenant file. See Keep a tenant in a file.
  • The pgw binary on the CI runner.
  • A network path from the runner to pgw’s admin API. Pass its URL with --admin <url>. The admin API serves plain HTTP, so put it behind HTTPS or a tunnel. The pgw command warns when --admin is an http URL to a non-loopback address, because the API key then crosses the network unencrypted.
  • PGW_API_KEY and each secret variable that the file names, set from your CI system’s secret store.

Set up the pipeline

1

Preview the plan

Run a dry run on every change to the file.
2

Hold the apply step for review

Use your CI system’s manual approval, such as a protected environment, so that a person reads the plan before the apply step runs.
3

Apply the change

pgw prints the plan, then applied:
A pipeline that never deletes needs neither --prune nor --yes.

Example: GitHub Actions

The following workflow previews the plan on each pull request that changes the file, and applies it on the main branch after an approval on the pgw-production environment.

How a sync decides when to ask

Without a terminal, a plan that deletes stops after the plan:
pgw exits with status 0 when it applies the plan, prints nothing to change, or finishes a dry run. Any error, a refused confirmation included, exits with status 1. A wrong flag or a missing argument exits with status 2.

Changes between the preview and the apply

Between the preview and the apply, someone else could change the tenant. Within one run, pgw catches this for a plan that deletes. It plans again inside the transaction, and if the result differs from the plan that it printed, it applies nothing and says the configuration changed since the preview; run sync again. This check covers a single run. A dry run in one job and an apply in a later job are two runs, so the applied plan can differ from the preview that the reviewer saw. Keep the apply job’s output, so that you can compare the plan that it printed with the one that the reviewer approved.

Handle a timeout

pgw config sync waits up to 3 minutes for pgw. When the command gets no answer, it reports that the sync may have been applied, because pgw finishes a plan that it started to apply. Run the sync again. It changes only what still differs.

Next steps

Keep a tenant in a file

Check which sections of the file --prune deletes from before you automate it.

CLI reference

Look up each flag and error of pgw config sync and pgw config export.