Syncs

A sync copies one environment of a project to a Vercel project or to GitHub Actions secrets, and keeps it up to date. envpass pushes after every change, so the destination never needs a token or a build step that pulls values.

A typical setup for one app:

Before you start

Setting up a sync takes two steps: a workspace connection to Vercel or GitHub, then a sync in each project.

• Adding a connection needs Manage service tokens in your workspace role.
• Adding a sync needs Manage service tokens in the project, through your workspace or project role, plus at least read on the environment.

Both need a user login. Service tokens can't manage connections or syncs. See Access control.

The Vercel or GitHub token you paste is encrypted at rest and never shown again, not even to admins. Removing a connection also deletes the syncs that use it.

Connect Vercel

1. In Vercel, open vercel.com/account/tokens and click Create Token.
2. Name it (for example envpass), set Scope to the team that owns your projects, and choose an expiration. Copy the token.
3. In envpass, open Integrations and click Connect Vercel.
4. Paste the token and click Check token.
5. Under Vercel scope, pick the team, or your personal account.
6. Optionally rename the connection, then click Save connection.

A connection writes to one Vercel scope. Connect again with another token for each other team.

Connect GitHub

1. In GitHub, open github.com/settings/personal-access-tokens and click Generate new token (fine-grained).
2. Set Resource owner to the user or organization that owns the repositories.
3. Under Repository access, pick Only select repositories and choose the ones you'll sync to.
4. Under Repository permissions, set Secrets to Read and write. To sync to GitHub environments, also set Environments to Read and write.
5. Generate the token and copy it. If the organization requires approval for fine-grained tokens, have an owner approve it.
6. In envpass, open Integrations, click Connect GitHub, paste the token, click Check token, then Save connection.

Add a sync

1. Open the project's Syncs tab and click Add sync.
2. Pick the Connection and the envpass Environment to copy.
3. Pick the destination:
   • Vercel: the Vercel project and Vercel environment (Production, Preview or Development). For Preview, you can enter a Git branch. Leave it empty to set values for every preview branch.
   • GitHub: the Repository and the Secrets scope: repository secrets, or one of the repository's GitHub environments. Create the environment in GitHub first (Settings → Environments).
4. Click Add sync. The first push starts right away.

One connection can't have two syncs writing to the same destination.

What gets pushed

A sync pushes the environment's team values, the same set a service token gets. Personal overrides are never pushed.

It runs:

• when you add or resume it, or click Sync now
• a couple of seconds after any change to team values in that project environment: edits, deletes, restores, renames, rollbacks, imports and promotes. Changes made close together go out in one run.

Each run only sends keys that are new, changed in envpass since the last push, or missing at the destination. Every run is recorded in the audit log as a read by the person who set up the sync.

Vercel

• New variables are created for the chosen environment (and branch) with the type Sensitive, or Encrypted for Development, which doesn't support Sensitive. Their comment is "Managed by envpass".
• If a variable with the same name already exists for exactly that environment, envpass updates its value and keeps its type.
• Vercel applies new values on the next deployment. Redeploy to use them right away.

GitHub

• Values are encrypted with the repository's (or GitHub environment's) public key before they leave envpass, as GitHub requires.
• Workflows get the new values on their next run, as ${{ secrets.NAME }}. Jobs that use environment secrets need environment: <name>.

What gets deleted

• When you delete or rename a key in envpass, the sync removes it from the destination, but only if envpass wrote it there.
• Variables at the destination that don't exist in envpass are never touched.
• If a key already existed at the destination when the sync started, envpass overwrites it and manages it from then on: deleting it in envpass deletes it there too.
• Pausing or deleting a sync, or removing its connection, leaves every value at the destination as it is.

Skipped keys

Some keys are skipped on purpose. The rest of the sync still runs, and the sync lists each skipped key with the reason:

Status and controls

The Syncs tab shows each sync's destination, environment and status: Queued, Syncing, In sync, Failed or Paused, with the last sync time, how many keys were created, updated and removed, and any skipped keys or error.

From a sync's menu:

• Sync now queues a run. It only pushes what changed or is missing.
• Pause stops runs on changes. Resume turns it back on and runs it once.
• Delete stops updating the destination. Values already there stay.

The same is available from the CLI with envpass syncs and from the API under /api/v1/workspaces/{workspaceId}/projects/{projectId}/syncs.

To get told when a sync fails, add a webhook for sync.failed. It can post to Slack.

Who a sync runs as

A sync reads values with the permissions of the person who set it up. If that person loses read on the environment or leaves the workspace, the sync fails with:

The person who set up this sync can no longer read this environment. Delete the sync and set it up again.

Delete it and add it again as someone who has access.

Retries

When Vercel or GitHub is down, rate-limits envpass, or can't be reached, the sync retries with growing gaps, up to 5 attempts over about 7 minutes. Keys pushed before a failure are remembered, so the next run picks up where it stopped.

Errors a retry can't fix, like a rejected token or missing permission, fail straight away. Either way, the status turns to Failed and a sync.failed event is sent. The next change or Sync now tries again.

Troubleshooting

Limits