Pipeline Integration
Inject secrets directly into your CI/CD pipelines. OIDC-native for GitHub Actions, GitLab, and CircleCI — no static tokens stored in your pipeline config.
How it works
Toknbase issues short-lived vault tokens to your pipeline via OIDC — your CI provider (GitHub, GitLab, CircleCI) issues a JWT scoped to that run, Toknbase verifies it cryptographically, and returns a 15-minute access token. No static credentials ever leave your vault.
OIDC or static token
OIDC is preferred — tokens expire with the run. Static tokens available for platforms without OIDC.
Cryptographic verification
JWT signature, expiry, issuer, audience, and subject all verified against the provider's JWKS endpoint.
Scoped access issued
A 15-minute vault token is issued — scoped to the declared project and environment only.
Secrets injected as env vars
All secrets masked automatically in CI logs. Every pull recorded on the on-chain audit log.
Credential scan workflow
Add credential exposure detection as a required check on every pull request. The scanner checks the full git history — not just the changed files — so secrets added in any prior commit are caught before merging.
Add your Toknbase token to GitHub Secrets
Repository → Settings → Secrets and variables → Actions → New repository secret. Name itTOKNBASE_TOKEN. Get the token value from Dashboard → Tokens → Service Identities (create with CI/CD scope).
read_only scope for scanning. It never writes to your vault.GitHub Actions — .github/workflows/toknbase-scan.yml
name: Toknbase Secret Scan
on:
push:
branches: [main, master]
pull_request:
branches: [main, master]
jobs:
scan:
runs-on: ubuntu-latest
name: Scan for exposed credentials
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0 # Full git history — don't skip this
- name: Install Toknbase CLI
run: npm install -g @toknbase/cli
- name: Authenticate
run: toknbase auth login --token ${{ secrets.TOKNBASE_TOKEN }}
- name: Scan repository
run: toknbase scan . --format json --output scan-results.json
- name: Check for critical findings
run: |
CRITICAL=$(cat scan-results.json | jq '[.findings[] | select(.severity =="critical")] | length')
if ["$CRITICAL" -gt"0" ]; then
echo"Found $CRITICAL critical credential exposures. Review scan-results.json."
exit 1
fifetch-depth: 0is required
Without it, GitHub Actions only checks out the latest commit and misses secrets in git history. Most credential exposures live in commits that were"fixed" by deletion but remain in the git log. Always setfetch-depth: 0.
Fail on critical findings only.Adjust the severity filter to match your policy. You can also fail onhighor all findings.
Scan results are saved as a build artifact.View them in the Actions tab for each run — or in your Toknbase dashboard under Scanner, where every CI scan is logged on-chain.
GitLab CI
.gitlab-ci.ymlAddTOKNBASE_TOKENas a CI/CD variable in your GitLab project settings (masked), then use this job:
scan-credentials:
image: node:20
script:
- npm install -g @toknbase/cli
- toknbase auth login --token $TOKNBASE_TOKEN
- toknbase scan . --format json --output scan-results.json
- |
CRITICAL=$(cat scan-results.json | jq '[.findings[] | select(.severity =="critical")] | length')
if ["$CRITICAL" -gt"0" ]; then
echo"Found $CRITICAL critical credential exposures."
exit 1
fi
artifacts:
paths:
- scan-results.json
when: always
only:
- merge_requests
- mainIntegrations
Copy the 5-line workflow block below
Add id-token: write to your job permissions
Done — no secrets to store, tokens expire in 15 min
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v4
- uses: toknbase/secrets-action@v1
with:
project: ${{ vars.TOKNBASE_PROJECT_ID }}
environment: productionEvery secret in theproductionenvironment is injected asenv.SECRET_NAMEin all subsequent steps. All values masked in logs automatically.
Scan workflow templates
3 ready-to-copyPick the template that matches how your team works. Copy, save to.github/workflows/, and push. No modifications needed except the branch name.
Runs on every PR. If Critical secrets are found, the check fails and the PR cannot be merged.
name: Toknbase Secret Scan
on:
pull_request:
branches: [main, master]
jobs:
scan:
name: Scan for exposed secrets
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Scan for secrets
run: npx @toknbase/cli scan . --fail-on critical --json > scan-results.json
env:
TOKNBASE_TOKEN: ${{ secrets.TOKNBASE_TOKEN }}
- name: Upload scan results
if: always()
uses: actions/upload-artifact@v4
with:
name: toknbase-scan-results
path: scan-results.jsonRuns on every push to main. Reports findings to your dashboard without blocking the push.
name: Toknbase Secret Monitor
on:
push:
branches: [main, master]
jobs:
monitor:
name: Monitor for exposed secrets
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v4
- name: Scan and report
run: npx @toknbase/cli scan . --json > scan-results.json || true
env:
TOKNBASE_TOKEN: ${{ secrets.TOKNBASE_TOKEN }}
- name: Upload results
uses: actions/upload-artifact@v4
with:
name: toknbase-monitor-results
path: scan-results.jsonRuns every Monday at 9am UTC. Scans your entire git history — useful for repos that existed before Toknbase.
name: Toknbase Weekly Scan
on:
schedule:
- cron: '0 9 * * 1' # Every Monday at 9am UTC
workflow_dispatch: # Also allows manual runs
jobs:
weekly-scan:
name: Full repository scan
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history scan
- name: Scan entire repository
run: npx @toknbase/cli scan . --json > weekly-scan.json || true
env:
TOKNBASE_TOKEN: ${{ secrets.TOKNBASE_TOKEN }}
- name: Upload weekly report
uses: actions/upload-artifact@v4
with:
name: weekly-scan-report-${{ github.run_number }}
path: weekly-scan.json
retention-days: 90Setting up your TOKNBASE_TOKEN
In your Toknbase dashboard, go to Tokens → Service Identities → Create new token
Name it something like"github-actions" so you know what it's for
Copy the token value — you can only see it once
In your GitHub repo: Settings → Secrets and variables → Actions → New repository secret
Name: TOKNBASE_TOKEN — paste your token as the value
Whattoknbase/secrets-action@v1does
Requests a short-lived OIDC JWT from GitHub's identity endpoint — scoped to this run only
Sends the JWT to Toknbase's JWKS endpoint for cryptographic verification (exp, iss, aud, kid)
Receives a 15-minute vault token — injected secrets are masked with ::add-mask:: before output
On-chain audit log:Every pull is permanently recorded — run ID, timestamp, secrets accessed. Tamper-evident, verifiable by anyone.
Security Practices
Use OIDC whenever possible
OIDC tokens expire with the CI run and cannot be replayed. They're the safest option — no rotation, no storage risk.
One token per pipeline / environment
Create separate tokens for staging and production. A compromise in staging does not affect production, and revocation is surgical.
Read-only scope for CI/CD
Unless your pipeline needs to create or update secrets, always use read-only scope. A compromised token cannot modify your vault.
Rotate static tokens regularly
If you can't use OIDC, rotate static CI tokens at least every 90 days. Set an expiry from the Tokens page — Toknbase will warn you when they're approaching expiry.
Audit CI access regularly
Review the Toknbase audit log for your CI tokens. Unexpected access patterns (wrong time, unknown run ID) are early indicators of a problem.
What's next