> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a sync in CI

> Preview a tenant file change in one pipeline step, and apply it with pgw config sync --yes after a person reviews the preview.

`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](https://docs.pgw.sipmicro.services/config-as-code/tenant-file.md).
* 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.

```bash theme={null}
pgw config sync pgw.yaml --prune --dry-run --admin https://pgw-admin.example.com
```

**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**

```bash theme={null}
pgw config sync pgw.yaml --prune --yes --admin https://pgw-admin.example.com
```

pgw prints the plan, then `applied`:

```text theme={null}
  - user pbx.example.com/1003
+0 ~0 -1
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.

```yaml theme={null}
name: pgw tenant
on:
  pull_request:
    paths: [pgw.yaml]
  push:
    branches: [main]
    paths: [pgw.yaml]

jobs:
  preview:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pgw config sync pgw.yaml --prune --dry-run --admin "$PGW_ADMIN"
        env:
          PGW_ADMIN: ${{ vars.PGW_ADMIN }}
          PGW_API_KEY: ${{ secrets.PGW_API_KEY }}
          PGW_PASSWORD_1001: ${{ secrets.PGW_PASSWORD_1001 }}

  apply:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: pgw-production
    steps:
      - uses: actions/checkout@v4
      - run: pgw config sync pgw.yaml --prune --yes --admin "$PGW_ADMIN"
        env:
          PGW_ADMIN: ${{ vars.PGW_ADMIN }}
          PGW_API_KEY: ${{ secrets.PGW_API_KEY }}
          PGW_PASSWORD_1001: ${{ secrets.PGW_PASSWORD_1001 }}
```

## How a sync decides when to ask

| Plan | In a terminal | Without a terminal, such as in CI |
| - | - | - |
| Creates and updates only | Applies without asking | Applies without asking |
| Deletes, without `--yes` | Asks `Apply these changes? [y/N]` | Refuses, and changes nothing |
| Deletes, with `--yes` | Applies without asking | Applies without asking |
| Any plan, with `--dry-run` | Prints the plan and changes nothing | Prints the plan and changes nothing |

Without a terminal, a plan that deletes stops after the plan:

```text theme={null}
  - user pbx.example.com/1003
+0 ~0 -1
pgw: deleting needs confirmation; run in a terminal or pass --yes
```

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

> [card] [Keep a tenant in a file](https://docs.pgw.sipmicro.services/config-as-code/tenant-file.md)
>
> Check which sections of the file `--prune` deletes from before you automate it.

> [card] [CLI reference](https://docs.pgw.sipmicro.services/reference/cli.md)
>
> Look up each flag and error of `pgw config sync` and `pgw config export`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.