Skip to content
PulsVaultDocs
Get started
Solo ProTeamBusinessEnterprise

Quickstart: first secret in CI

Create a namespace, a service account and an API key, write a secret, and read it from a pipeline — in five steps.

This walks the whole loop: provision access in the console, then read a secret from a machine. It takes about five minutes.

1. Create a namespace#

Open your project → Secrets → Namespaces, pick an environment tab (e.g. prod), and create a namespace such as product/web. A namespace mints its own encryption key, so this requires the engine to be unsealed.

Secrets live inside a project, so every path starts with the project slug — acme-web in the examples below. See The Shared project for the one project PulsVault creates for you.

2. Create a machine identity#

Go to Secrets → Machine Identities → New. Give it a name (e.g. GitHub Actions) and a slug (github-actions). The slug is how the machine appears in the audit trail.

3. Attach a policy#

In the wizard's second step, grant scoped access — for example actions read on the pattern acme-web/prod/product/web/**. Policies match the full canonical path {project}/{env}/{namespace}/{secret}. See Access policies.

4. Issue an API key#

In the third step (or later, from the account's API Keys tab), issue a key. The token is shown once:

Copy it now — you can't see it again

Only a SHA-256 hash of the token is stored. If you lose it, revoke the key and issue a new one. Store it as an encrypted CI secret (e.g. a GitHub Actions secret named PULSVAULT_TOKEN).

5. Write and read the secret#

Write a value once (from the CLI, using a key that also has write):

bash
pulsvault login                            # paste the key at the prompt; input is hidden
pulsvault set acme-web/prod/product/web/db/password --from-file ./password.txt

login checks the key against the server before storing it, so a mistyped or revoked key fails here rather than later. Running your own PulsVault instance? Point the CLI at it once with pulsvault login --profile mycorp --host https://vault.mycorp.com/api/v1 — see Pointing the CLI at your own deployment.

Then read it from your pipeline. With the CLI:

bash
export DATABASE_PASSWORD=$(pulsvault get acme-web/prod/product/web/db/password)

Set --project (or PULSVAULT_PROJECT) once and you can drop the leading slug:

bash
export PULSVAULT_PROJECT=acme-web
pulsvault get prod/product/web/db/password

To store it on the machine instead of re-exporting it in every shell, use pulsvault config project acme-web — see Profiles & defaults.

…or with plain curl:

bash
curl -H "Authorization: Bearer $PULSVAULT_TOKEN" \
  https://api.pulsvault.com/api/v1/secrets/acme-web/prod/product/web/db/password
# → {"path":"…","value":"…","versionNumber":1,"contentType":"text/plain","metadata":{}}

Next: make it known-working#

Storing a secret is half the job. In the console, attach a validation probe to the path — that is what turns a stored string into a credential PulsVault keeps confirming still authenticates. Nothing validates until you do this; the CLI can run and read probes, never create them.

Once it is attached, the same path answers from your terminal or a pipeline:

bash
pulsvault validation-status acme-web/prod/product/web/db   # is it validated, and was it working?
pulsvault validate acme-web/prod/product/web/db && ./deploy.sh   # check it right now, then deploy
Was this page helpful?