CI / Secrets and trust
Set preview secrets from an integration
Each pull request of your app gets its own database, like a Neon branch, and its preview job needs the URL of that database. A token with the action secrets:preview lets your integration set a value for one branch, and nothing else.
4 min read
An admin cannot set a new value by hand for every pull request, and you do not want to give your integration an admin token. A CI secret can have a value for one branch in the preview environment. Runs of that branch, and of its pull request, take it before the shared value of preview. The forge deletes it when the branch is deleted, or when its last open pull request closes or merges.
You need:
- Admin access to the repository, to create the secret.
- Write access, to make the token of the integration.
1. Create the secret once
An admin creates the secret, with its hosts and its header, and a shared value for preview. Bind the host and the request header that your job sends the URL in, for example a database driver that talks HTTPS:
src secret set DATABASE_URL --env preview --host ep-example.neon.tech --header Neon-Connection-String < shared-preview-url.txt
A value for one branch cannot create a secret, or change its hosts or its header.
2. Make a token for the integration
- Open Settings, Tokens.
- Add the repository, open Advanced: pick single actions, and pick only
secrets:preview. - Pick an end time, then click Create token.
People with write access can make this token. See Make an access token.
3. Set the value when the branch gets its database
In the integration, after it made the database of the branch, set the value for the branch. src reads the token from SRC_TOKEN (see Use src in scripts), and the value from standard input:
neonctl branches create --name "preview/$BRANCH"
neonctl connection-string "preview/$BRANCH" | src secret set DATABASE_URL --env preview --branch "$BRANCH" -R acme/app
Or call the REST API:
curl -X PUT "https://source.tanstack.com/api/v1/repos/acme/app/ci/secrets/DATABASE_URL/branches/$BRANCH" \
-H "Authorization: Bearer $SRC_TOKEN" -H 'Content-Type: application/json' \
--data "{\"value\": \"$DATABASE_URL\"}"
An MCP client calls set_preview_secret with name, branch and value.
4. Use it in the preview job
The job names the environment, as for any secret:
.job('preview', { environment: 'preview', secrets: { DATABASE_URL: {} }, egress: ['ep-example.neon.tech'], steps })
Done
A run of the pull request of $BRANCH gets the value of that branch. Other pull requests get the shared value of preview.
Open Settings, then Secrets under Code, and pick preview. A secret with branch values has a 2 branch values button under its row. Click it to list the branches, each with a Delete button.

Tip
The value of a branch shadows the shared value of preview for the runs of that branch and its pull request. When a preview job gets a value that you did not expect, look here first.
Delete a value sooner
The forge deletes the values of a branch when the branch is deleted, or when its last open pull request closes or merges. To delete one sooner:
src secret delete DATABASE_URL --env preview --branch "$BRANCH"
In the Secrets section of Settings, open the branch values of the secret and click Delete next to the branch. People with write access can do this, like the token.
Rules
- A value for one branch exists only in
preview, for a secret that an admin created. It is write-only, like every secret value. - The branch must exist and must not be protected: the default branch, a tag or a branch with a branch rule is refused. Only admins pick what a protected run gets. A branch that gets a rule later keeps its value, but its runs take the shared value of preview.
- Runs of the branch and of its pull request take it first, with the shared value of preview as the fallback. A pull request from a fork never takes it: its branch is in another repository.
secrets:previewneeds write access. A token with it cannot read, list or change secrets, and the Write preset of the tokens page includes it.- A repository keeps at most 500 values for branches, all secrets together.
REST and MCP:
GET /ci/secretsandlist_ci_secretsshow admins the branches that have a value. The Secrets section of Settings lists them under their secret whenpreviewis picked, with a count and a Delete button for each branch. It never shows a value.- REST:
PUT /ci/secrets/<name>/branches/<branch>({ "value" }) andDELETE /ci/secrets/<name>/branches/<branch>. - MCP:
set_preview_secret,delete_preview_secret.