Docs

GitHub Actions

Connect a project to GitHub once, and ApiVault keeps what it manages there in step with your keys.

How it works

The GitHub integration pushes your keys into a repository's Actions secrets and into the secrets of a named deployment environment inside it. Syncing runs on the same triggers as Vercel: key changes when auto-sync is on, the retry sweep, and Sync now, which previews every change first. GitHub never reveals a secret's value, so ApiVault tracks only what it wrote and when GitHub says each secret last changed.

Connecting GitHub

Click Connect GitHub on the project's GitHub page. GitHub asks which of your GitHub accounts to authorize with — the one you pick is how ApiVault confirms the installation is yours. If you have not installed ApiVault's GitHub App yet, GitHub then asks you to install it on an account or organization and to choose which repositories it may reach. You come back to the project and can add any repository you selected.

If the GitHub user you authorized with can reach the app on more than one account or organization, ApiVault asks which one this project should sync to. That list holds your own account and the organizations you authorized with. Another person's personal account is never on it, even when GitHub reports the installation to you because you collaborate on its repositories, and neither are accounts this project already runs on. Only accounts that already have the app can be connected; the chooser links to GitHub to install it on one that doesn't, which is how a newly created organization joins the list.

One installation can serve several ApiVault projects: connecting a second project reuses the installation you already have, without a second trip through GitHub's install screen. To sync to repositories under a different account or organization, click Connect Another GitHub Account; each account gets its own connection.

No GitHub token is stored. The connection holds only an installation id. For each sync, ApiVault mints a short-lived token from that installation, uses it, and lets it expire.

Permissions ApiVault asks for

GitHub asks you to approve these on the repositories you pick:

  • Secrets (read and write) — create, update and delete the Actions secrets ApiVault manages.
  • Environments (read and write) — create, update and delete secrets inside a deployment environment.
  • Actions (read) — list the repository's deployment environments so you can choose one.
  • Administration (read and write) — create a deployment environment that doesn't exist yet, when you map an environment to a new name.
Why Administration?
GitHub bundles environment creation into its broad repository-admin permission, which also covers renaming a repository, changing its visibility and managing collaborators. ApiVault uses it for one thing only: creating a deployment environment you asked for. It never changes any other repository setting.

Repository and environment targets

Each ApiVault environment can go to the repository's own Actions secrets or to one named deployment environment. Environments are discovered per repository, so the choices you see are the ones that repository has. You can also type a name that matches nothing:

  • A name that matches no environment is created in the repository, under exactly the name you typed. The sync preview lists each creation in a group of its own before anything happens.
  • A name that differs from an existing environment only in letter case snaps onto that environment instead of creating a second one.
  • A name must be non-empty, at most 255 characters, and must not contain any of " < > \ / : * ? |.

Deployment environments are not available on private repositories on the GitHub Free plan. On those, the environment targets are unavailable and only repository secrets can be used.

ApiVault never deletes a deployment environment
This holds even for one ApiVault created. A workflow can reference an environment by name, so a missing one breaks the workflow while an empty one is harmless. Unlinking removes the secrets ApiVault owns and leaves the environment in place.

What ApiVault changes in GitHub

ApiVault keeps its own list of the secrets it created for each link and target and only updates or deletes those. A secret with the same name that you created yourself is a conflict: that key is skipped on that target and the others still sync. Delete or rename your copy, then click Sync now.

Drift is reported. GitHub reports when each secret last changed, so ApiVault can tell when a secret it manages was edited on GitHub. The vault wins and its value is restored, but the change is reported rather than passing unnoticed. A drifted secret that is no longer in the vault is left in place and reported, not deleted.

Access, suspension and removal

Unlink deletes the secrets ApiVault created and removes the link. Disconnect unlinks every repository and removes the connection. Disconnecting does not uninstall the GitHub App: the installation stays until you remove it on GitHub, under Settings → Applications.

A suspended installation recovers by itself once you unsuspend it in GitHub. An uninstalled one needs reconnecting. A repository removed from the installation stops syncing until you add it back in GitHub.

An uninstalled app is recognised the first time ApiVault tries to use the installation, so the connection switches itself to Access lost rather than reporting the repositories as missing, whether or not GitHub's webhook reached the server.

Reconnect on a connection stays on that connection's GitHub account: it never connects a different account, and if the app is no longer installed there it sends you to GitHub to install it again. Installing it again gives the account a new installation id, and the connection you already had takes it over — your linked repositories come with it and each one is queued to sync, so one account stays one connection.

If ApiVault cannot verify who installed the app, the connection is saved but switched off, and nothing syncs until you connect again and approve the authorization request.