Boundaries
The three-action pattern is the standard across Bitwarden's CI, CD, and operational workflows —
treat any other retrieval mechanism in a Bitwarden workflow as a finding.
Defer to the linter skill. For anything the workflow linter enforces (e.g.
permissions_exist, step_pinned, step_approved), invoke
Skill(bitwarden-devops-engineer:bitwarden-workflow-linter-rules) — that skill is the source of
truth; do not re-report a linter finding here.
Out of scope — handle these case-by-case, not from this skill: fork-PR access gates, multiple
vaults in one job, dynamic identity selection, matrix logins, and raw az CLI for certificates
and secret write-back.
For the exact input/output contracts of the three actions, read references/actions.md.
Secret exposure is the overriding concern
Keeping a retrieved secret from being exposed outranks every other consideration in this skill. An
exposed token is a CRITICAL incident. Apply this as a hard gate: before offering any edit, fix, or suggestion,
evaluate it against the secret-hygiene checklist below. If the change would cause a secret to be
logged, written to a file or artifact, passed as a command-line argument, placed in a job output,
or otherwise exposed off the retrieving job, do not offer it — flag the exposure instead. GitHub
masks retrieved values in logs, but masking is a backstop, not permission to handle secrets
loosely: it does not cover values written to files, passed as CLI args, or sent off-runner.
This gate is independently evaluable — each item in the secret-hygiene checklist
is a concrete pass/fail check against the job you touched. Run it every time.
The AKV + OIDC lifecycle
Every job that needs a Key Vault secret follows the same four-beat sequence:
azure-login → get-keyvault-secrets → azure-logout → consume the step outputs
jobs:
my-job:
runs-on: ubuntu-24.04
permissions:
contents: read
id-token: write # OIDC federated login needs this — see golden rule 2
steps:
- name: Log in to Azure
uses: bitwarden/gh-actions/azure-login@main
with:
subscription_id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
tenant_id: ${{ secrets.AZURE_TENANT_ID }}
client_id: ${{ secrets.AZURE_CLIENT_ID }}
- name: Get Azure Key Vault secrets
id: secrets
uses: bitwarden/gh-actions/get-keyvault-secrets@main
with:
keyvault: KEY-VAULT
secrets: "SECRET-NAME-1,SECRET-NAME-2"
- name: Log out from Azure
uses: bitwarden/gh-actions/azure-logout@main
- name: Do work
env:
MY_TOKEN: ${{ steps.secrets.outputs.SECRET-NAME-1 }} # step outputs survive logout
run: ./do-work.sh
KEY-VAULT and SECRET-NAME-1 / SECRET-NAME-2 are placeholders. Substitute the vault and secret names
supplied for the task. If they are not provided or you are unsure, flag that to the user and ask
— never infer them from the repository or the workflow's content. See the authoring procedure.
The Azure session is only needed to fetch the secrets. Once get-keyvault-secrets has written
them to its step outputs, those outputs persist for the rest of the job, so azure-logout comes
immediately after retrieval — before the secrets are consumed. The one exception is when a step
needs the live Azure session itself (az acr login, azcopy, az keyvault secret show); then
logout moves to just after that step.
Two conventions worth applying every time:
Give the retrieval step id: secrets (not get-kv-secrets or retrieve-secrets). It reads
clearly at the point of use — steps.secrets.outputs.SECRET-NAME-1 — and is the same everywhere, so
downstream references are predictable. Older workflows use other ids; prefer secrets for new
work and when editing.
Wrap three or more secrets in a folded block scalar, one per line, so the list stays readable
and diffs cleanly. Two or fewer can stay inline as a quoted string:
secrets: >-
SECRET-NAME-1,
SECRET-NAME-2,
SECRET-NAME-3
Output names are case-insensitive in GitHub expressions, so both
steps.secrets.outputs.SECRET-NAME-1 and ...outputs.secret-name-1 resolve. Match the secret name
as written for readability.
Golden rules (invariants)
Treat a deviation as a finding.
Internal actions float on @main; third-party actions are SHA-pinned. Every
bitwarden/gh-actions/* reference uses @main — never a SHA. Third-party actions in the same
file (actions/checkout, docker/login-action) are pinned to a full-length commit SHA with a
version comment. Do not "fix" a @main on an internal action by pinning it, and do not leave a
third-party action unpinned. (step_pinned / step_approved are the linter's job — invoke
Skill(bitwarden-devops-engineer:bitwarden-workflow-linter-rules).)
Any job that logs in declares id-token: write. OIDC federated login fails without it. Keep
the rest of the permissions: block minimal (usually contents: read plus whatever the real
work needs). Bitwarden repos default to permissions: {} at the workflow level and grant
narrowly per job.
Only three GitHub secrets exist for auth — the OIDC triad. AZURE_SUBSCRIPTION_ID,
AZURE_TENANT_ID, AZURE_CLIENT_ID. Everything else lives in Key Vault. The client_id
sometimes uses a purpose-specific identity, and their scope (org, repo, or environment) is a
repo setting you cannot read from the workflow; see references/actions.md for both.
Always pair azure-login with azure-logout, and match their conditions. Omitting logout
leaves credentials active in the runner. If azure-login is gated with if:, azure-logout
must carry the same condition, or it runs against a session that was never created.
Treat secret exposure as the thing that matters most — see "Secret exposure is the overriding
concern" above and run the secret-hygiene checklist on every job you touch. Consume every secret
through a step-scoped env:, never interpolate one directly into a run: command line, and
never echo, cat, or log it.
Getting a secret to a downstream job or reusable workflow
A secret's value belongs to the job that retrieved it. How you reach further depends on the
distance the secret has to travel.
Same job, later step — reference the retrieval step's output through a step-scoped env: (shown
in the lifecycle above). This is the only case where a raw value is passed around, and it never
leaves the job.
A subsequent job — do not pass the value across the boundary. GitHub redacts masked values
out of job outputs: — the runner logs Skip output <key> since it may contain secret — and
get-keyvault-secrets registers every value it retrieves as masked. So a secret placed in an
output arrives empty downstream; a value that was never masked would cross in the clear.
Either way, never put a secret in a job output:. Only two things legitimately cross a job
boundary:
The ability to mint a short-lived GitHub App token, when the real need is GitHub access
(cross-repo checkout, dispatch, gh api). The minted token is itself masked, so it cannot
travel through outputs: either — mint it in the job that consumes it. What crosses the
boundary is the capability, not a token: each job retrieves the App id/key from AKV and mints
its own.
In the job that needs GitHub access:
- name: Get Azure Key Vault secrets
id: secrets
uses: bitwarden/gh-actions/get-keyvault-secrets@main
with:
keyvault: KEY-VAULT
secrets: "GH-APP-ID,GH-APP-KEY"
- uses: bitwarden/gh-actions/azure-logout@main
- name: Generate GH App token
id: app-token
uses: actions/create-github-app-token@<full-40-char-sha> # vX.Y.Z — replace both with the real values
with:
app-id: ${{ steps.secrets.outputs.GH-APP-ID }}
private-key: ${{ steps.secrets.outputs.GH-APP-KEY }}
owner: ${{ github.repository_owner }}
repositories: self-host # narrow the token's scope when possible
- uses: actions/checkout@<full-40-char-sha> # vX.Y.Z — replace both with the real values
with:
token: ${{ steps.app-token.outputs.token }}
KEY-VAULT, GH-APP-ID, and GH-APP-KEY are placeholders — use the vault and App-credential
secret names given for the task. Whether the App credentials live in an org-wide vault or a
repo-scoped one is a per-task detail; if you do not have it, ask rather than assuming.
<full-40-char-sha> is a placeholder too: never emit it literally and never guess a SHA. Look up
the real commit SHA for the version you want and replace both the ref and the # vX.Y.Z comment,
per golden rule 1.
A second job that also needs GitHub access repeats this whole block. Do not try to shorten it by
routing steps.app-token.outputs.token through a job output: — it is masked, so the downstream
job receives an empty string and the failure looks like a permissions error.
Non-secret derived values via job outputs: — a version string, a boolean, or even the
name of a secret key for the next job to look up (never the value). If the downstream job just
needs the same secret, the simplest answer is to re-run login → retrieve → logout in that job.
Each job authenticates independently.
A reusable workflow — the caller forwards the OIDC triad; the reusable workflow does its own
login/retrieve inside each job. This is a two-sided change — never edit only the caller.
Same repo (./.github/workflows/_x.yml): secrets: inherit on the uses: job.
Another repo (bitwarden/gh-actions/.github/workflows/_x.yml@main): pass the triad
explicitly. secrets: inherit does work cross-repo within the bitwarden org, but the convention
is explicit passing — it keeps least privilege (only the three secrets travel, not every secret
the caller can see) and documents the contract at the call site.
jobs:
review:
uses: bitwarden/gh-actions/.github/workflows/_review-code.yml@main
secrets:
AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
permissions:
contents: read
id-token: write # OIDC token is minted against the caller job's permissions
The callee must agree, or the values arrive empty: it declares each secret under
on.workflow_call.secrets: (with required: true where it cannot run without them). The
caller job must grant id-token: write — a callee can only narrow the caller's permissions,
never widen them — and every callee job that declares its own permissions: block must list
id-token: write explicitly, because declaring a block replaces the inherited set rather than
adding to it. Since Bitwarden workflows default to permissions: {} at the workflow level, in
practice both sides need it spelled out.
on:
workflow_call:
secrets:
AZURE_SUBSCRIPTION_ID: { required: true }
AZURE_TENANT_ID: { required: true }
AZURE_CLIENT_ID: { required: true }
If you own only the caller and the callee lives in bitwarden/gh-actions, read its
on.workflow_call block and match the names exactly rather than guessing.
Authoring procedure
When asked to add or correct secret retrieval in a job:
- Confirm the secret genuinely needs AKV. Pure CI steps (
format, lint, test, build
with no external service) usually need no secrets. See "When AKV is needed" below.
- Use the vault and secret names you were given — never infer them. The
keyvault and
secrets values are supplied per task. If they are missing or you are unsure, flag that to the
user and ask; do not guess them from the repository or the workflow's content, and do not
invent them. In drafts and examples, use the placeholders KEY-VAULT for the vault and
SECRET-NAME-1, SECRET-NAME-2 for secret names until the real values are confirmed.
- Wire
azure-login → get-keyvault-secrets → azure-logout in the job, using id: secrets on
the retrieval step.
- Ensure
id-token: write is on the job, and keep the surrounding permissions: minimal.
- Place
azure-logout correctly — right after retrieval, unless a later step needs the live
session, and matching any if: on the login.
- Use
@main for the internal actions; SHA-pin any third-party action you add. Resolve the
real full-length SHA and its version comment — never guess one, and never leave a
<full-40-char-sha> placeholder in a workflow you hand back.
- If the secret must reach another job or a reusable workflow, use the mechanism above —
re-retrieve per job, mint an App token for GitHub access, or forward the OIDC triad to the
reusable workflow. If a reusable workflow is involved, edit both sides: match the caller's
secrets: keys to the callee's on.workflow_call.secrets: declarations, and confirm each
logging-in job carries id-token: write.
- Run the secret-hygiene checklist before finishing.
Secret hygiene checklist
Because an exposed token is a critical failure, verify each of these on any job you touch:
- Every secret is consumed through a step-scoped
env:, not inlined into a run: argument.
- No step
echos, cats, prints, or writes a secret to a log, artifact, or committed file.
- The retrieval step uses
id: secrets and pulls only the secrets that job actually uses — no
speculative extras.
azure-logout runs as early as possible, and the job's permissions: are the minimum required.
When AKV is needed
| Capability |
Why AKV is involved |
| Container registry push |
az acr login (needs live session) or a registry token from AKV |
| External service integration |
API keys, connection strings, third-party tokens |
| Failure / status notifications |
Notification webhook URLs (e.g. Slack) retrieved from AKV |
For pure CI capabilities with no external interaction, AKV steps are typically unnecessary — and
azure-login cannot succeed on a pull_request run from a fork. pull_request_target and
workflow_run do receive secrets, but choosing a trigger is a fork-PR access gate — out of scope
here; ask.
References
references/actions.md — input/output contracts for azure-login (including its built-in
retry/backoff), azure-logout, and get-keyvault-secrets; plus how vault and secret names are
supplied and the OIDC client-identity conventions.
Skill(bitwarden-devops-engineer:bitwarden-workflow-linter-rules) — source of truth for all
linted rules; invoke it for
permissions_exist, step_pinned, step_approved, and anything bwwl checks.
1---2name: managing-workflow-secrets3description: >-4 Bitwarden's canonical pattern for using a secret inside a GitHub Actions job: authenticate to5 Azure with the OIDC triad, pull the secret from an Azure Key Vault via the bitwarden/gh-actions6 composite actions (azure-login → get-keyvault-secrets → azure-logout), consume it safely, and7 get it beyond the job or into a reusable workflow when needed. Use when questions like "add a8 step to pull the DockerHub token from Key Vault before we push the image", "do I need9 id-token: write on this job that logs in to Azure", or "my deploy job can't see the secret the10 build job retrieved" come up. Read alongside bitwarden-workflow-linter-rules, the source of11 truth for linted rules; prefer this skill over generic GitHub Actions advice, which diverges12 from the Bitwarden conventions.13allowed-tools: Read, Glob, Grep, Edit14metadata:15 source: https://skillmd.com/skills/bitwarden/managing-workflow-secrets16---1718## Boundaries1920The three-action pattern is the standard across Bitwarden's CI, CD, and operational workflows —21treat any other retrieval mechanism in a Bitwarden workflow as a finding.2223**Defer to the linter skill.** For anything the workflow linter enforces (e.g.24`permissions_exist`, `step_pinned`, `step_approved`), invoke25`Skill(bitwarden-devops-engineer:bitwarden-workflow-linter-rules)` — that skill is the source of26truth; do not re-report a linter finding here.2728**Out of scope** — handle these case-by-case, not from this skill: fork-PR access gates, multiple29vaults in one job, dynamic identity selection, matrix logins, and raw `az` CLI for certificates30and secret write-back.3132For the exact input/output contracts of the three actions, read `references/actions.md`.3334## Secret exposure is the overriding concern3536Keeping a retrieved secret from being exposed outranks every other consideration in this skill. An37exposed token is a CRITICAL incident. Apply this as a hard gate: **before offering any edit, fix, or suggestion,38evaluate it against the secret-hygiene checklist below. If the change would cause a secret to be39logged, written to a file or artifact, passed as a command-line argument, placed in a job output,40or otherwise exposed off the retrieving job, do not offer it** — flag the exposure instead. GitHub41masks retrieved values in logs, but masking is a backstop, not permission to handle secrets42loosely: it does not cover values written to files, passed as CLI args, or sent off-runner.4344This gate is independently evaluable — each item in the [secret-hygiene checklist](#secret-hygiene-checklist)45is a concrete pass/fail check against the job you touched. Run it every time.4647## The AKV + OIDC lifecycle4849Every job that needs a Key Vault secret follows the same four-beat sequence:5051```52azure-login → get-keyvault-secrets → azure-logout → consume the step outputs53```5455```yaml56jobs:57 my-job:58 runs-on: ubuntu-24.0459 permissions:60 contents: read61 id-token: write # OIDC federated login needs this — see golden rule 262 steps:63 - name: Log in to Azure64 uses: bitwarden/gh-actions/azure-login@main65 with:66 subscription_id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}67 tenant_id: ${{ secrets.AZURE_TENANT_ID }}68 client_id: ${{ secrets.AZURE_CLIENT_ID }}6970 - name: Get Azure Key Vault secrets71 id: secrets72 uses: bitwarden/gh-actions/get-keyvault-secrets@main73 with:74 keyvault: KEY-VAULT75 secrets: "SECRET-NAME-1,SECRET-NAME-2"7677 - name: Log out from Azure78 uses: bitwarden/gh-actions/azure-logout@main7980 - name: Do work81 env:82 MY_TOKEN: ${{ steps.secrets.outputs.SECRET-NAME-1 }} # step outputs survive logout83 run: ./do-work.sh84```8586`KEY-VAULT` and `SECRET-NAME-1` / `SECRET-NAME-2` are **placeholders**. Substitute the vault and secret names87supplied for the task. If they are not provided or you are unsure, **flag that to the user and ask**88— never infer them from the repository or the workflow's content. See the authoring procedure.8990The Azure session is only needed to _fetch_ the secrets. Once `get-keyvault-secrets` has written91them to its step outputs, those outputs persist for the rest of the job, so `azure-logout` comes92**immediately after retrieval** — before the secrets are consumed. The one exception is when a step93needs the live Azure session itself (`az acr login`, `azcopy`, `az keyvault secret show`); then94logout moves to just after that step.9596Two conventions worth applying every time:9798- **Give the retrieval step `id: secrets`** (not `get-kv-secrets` or `retrieve-secrets`). It reads99 clearly at the point of use — `steps.secrets.outputs.SECRET-NAME-1` — and is the same everywhere, so100 downstream references are predictable. Older workflows use other ids; prefer `secrets` for new101 work and when editing.102- **Wrap three or more secrets in a folded block scalar**, one per line, so the list stays readable103 and diffs cleanly. Two or fewer can stay inline as a quoted string:104105 ```yaml106 secrets: >-107 SECRET-NAME-1,108 SECRET-NAME-2,109 SECRET-NAME-3110 ```111112Output names are **case-insensitive** in GitHub expressions, so both113`steps.secrets.outputs.SECRET-NAME-1` and `...outputs.secret-name-1` resolve. Match the secret name114as written for readability.115116## Golden rules (invariants)117118Treat a deviation as a finding.1191201. **Internal actions float on `@main`; third-party actions are SHA-pinned.** Every121 `bitwarden/gh-actions/*` reference uses `@main` — never a SHA. Third-party actions in the same122 file (`actions/checkout`, `docker/login-action`) are pinned to a full-length commit SHA with a123 version comment. Do not "fix" a `@main` on an internal action by pinning it, and do not leave a124 third-party action unpinned. (`step_pinned` / `step_approved` are the linter's job — invoke125 `Skill(bitwarden-devops-engineer:bitwarden-workflow-linter-rules)`.)1261272. **Any job that logs in declares `id-token: write`.** OIDC federated login fails without it. Keep128 the rest of the `permissions:` block minimal (usually `contents: read` plus whatever the real129 work needs). Bitwarden repos default to `permissions: {}` at the workflow level and grant130 narrowly per job.1311323. **Only three GitHub secrets exist for auth — the OIDC triad.** `AZURE_SUBSCRIPTION_ID`,133 `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`. Everything else lives in Key Vault. The `client_id`134 sometimes uses a purpose-specific identity, and their scope (org, repo, or environment) is a135 repo setting you cannot read from the workflow; see `references/actions.md` for both.1361374. **Always pair `azure-login` with `azure-logout`, and match their conditions.** Omitting logout138 leaves credentials active in the runner. If `azure-login` is gated with `if:`, `azure-logout`139 must carry the _same_ condition, or it runs against a session that was never created.1401415. **Treat secret exposure as the thing that matters most** — see "Secret exposure is the overriding142 concern" above and run the secret-hygiene checklist on every job you touch. Consume every secret143 through a step-scoped `env:`, never interpolate one directly into a `run:` command line, and144 never `echo`, `cat`, or log it.145146## Getting a secret to a downstream job or reusable workflow147148A secret's value belongs to the job that retrieved it. How you reach further depends on the149distance the secret has to travel.150151**Same job, later step** — reference the retrieval step's output through a step-scoped `env:` (shown152in the lifecycle above). This is the only case where a raw value is passed around, and it never153leaves the job.154155**A subsequent job** — do **not** pass the value across the boundary. GitHub redacts masked values156out of job `outputs:` — the runner logs `Skip output <key> since it may contain secret` — and157`get-keyvault-secrets` registers every value it retrieves as masked. So a secret placed in an158output arrives **empty** downstream; a value that was never masked would cross in the clear.159Either way, never put a secret in a job `output:`. Only two things legitimately cross a job160boundary:161162- **The ability to mint a short-lived GitHub App token**, when the real need is GitHub access163 (cross-repo checkout, dispatch, `gh api`). The minted token is itself masked, so it cannot164 travel through `outputs:` either — **mint it in the job that consumes it**. What crosses the165 boundary is the capability, not a token: each job retrieves the App id/key from AKV and mints166 its own.167168 In the job that needs GitHub access:169170 ```yaml171 - name: Get Azure Key Vault secrets172 id: secrets173 uses: bitwarden/gh-actions/get-keyvault-secrets@main174 with:175 keyvault: KEY-VAULT176 secrets: "GH-APP-ID,GH-APP-KEY"177 - uses: bitwarden/gh-actions/azure-logout@main178 - name: Generate GH App token179 id: app-token180 uses: actions/create-github-app-token@<full-40-char-sha> # vX.Y.Z — replace both with the real values181 with:182 app-id: ${{ steps.secrets.outputs.GH-APP-ID }}183 private-key: ${{ steps.secrets.outputs.GH-APP-KEY }}184 owner: ${{ github.repository_owner }}185 repositories: self-host # narrow the token's scope when possible186 - uses: actions/checkout@<full-40-char-sha> # vX.Y.Z — replace both with the real values187 with:188 token: ${{ steps.app-token.outputs.token }}189 ```190191 `KEY-VAULT`, `GH-APP-ID`, and `GH-APP-KEY` are placeholders — use the vault and App-credential192 secret names given for the task. Whether the App credentials live in an org-wide vault or a193 repo-scoped one is a per-task detail; if you do not have it, ask rather than assuming.194 `<full-40-char-sha>` is a placeholder too: never emit it literally and never guess a SHA. Look up195 the real commit SHA for the version you want and replace both the ref and the `# vX.Y.Z` comment,196 per golden rule 1.197198 A second job that also needs GitHub access repeats this whole block. Do not try to shorten it by199 routing `steps.app-token.outputs.token` through a job `output:` — it is masked, so the downstream200 job receives an empty string and the failure looks like a permissions error.201202- **Non-secret derived values** via job `outputs:` — a version string, a boolean, or even the203 _name_ of a secret key for the next job to look up (never the value). If the downstream job just204 needs the same secret, the simplest answer is to **re-run login → retrieve → logout** in that job.205 Each job authenticates independently.206207**A reusable workflow** — the caller forwards the OIDC triad; the reusable workflow does its own208login/retrieve inside each job. This is a **two-sided change — never edit only the caller.**209210- **Same repo** (`./.github/workflows/_x.yml`): `secrets: inherit` on the `uses:` job.211- **Another repo** (`bitwarden/gh-actions/.github/workflows/_x.yml@main`): pass the triad212 explicitly. `secrets: inherit` does work cross-repo within the `bitwarden` org, but the convention213 is explicit passing — it keeps least privilege (only the three secrets travel, not every secret214 the caller can see) and documents the contract at the call site.215216 ```yaml217 jobs:218 review:219 uses: bitwarden/gh-actions/.github/workflows/_review-code.yml@main220 secrets:221 AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}222 AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}223 AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}224 permissions:225 contents: read226 id-token: write # OIDC token is minted against the caller job's permissions227 ```228229 The callee must agree, or the values arrive empty: it declares each secret under230 `on.workflow_call.secrets:` (with `required: true` where it cannot run without them). The231 **caller** job must grant `id-token: write` — a callee can only narrow the caller's permissions,232 never widen them — and every callee job that declares its own `permissions:` block must list233 `id-token: write` explicitly, because declaring a block replaces the inherited set rather than234 adding to it. Since Bitwarden workflows default to `permissions: {}` at the workflow level, in235 practice both sides need it spelled out.236237 ```yaml238 on:239 workflow_call:240 secrets:241 AZURE_SUBSCRIPTION_ID: { required: true }242 AZURE_TENANT_ID: { required: true }243 AZURE_CLIENT_ID: { required: true }244 ```245246 If you own only the caller and the callee lives in `bitwarden/gh-actions`, read its247 `on.workflow_call` block and match the names exactly rather than guessing.248249## Authoring procedure250251When asked to add or correct secret retrieval in a job:2522531. **Confirm the secret genuinely needs AKV.** Pure CI steps (`format`, `lint`, `test`, `build`254 with no external service) usually need no secrets. See "When AKV is needed" below.2552. **Use the vault and secret names you were given — never infer them.** The `keyvault` and256 `secrets` values are supplied per task. If they are missing or you are unsure, **flag that to the257 user and ask**; do not guess them from the repository or the workflow's content, and do not258 invent them. In drafts and examples, use the placeholders `KEY-VAULT` for the vault and259 `SECRET-NAME-1`, `SECRET-NAME-2` for secret names until the real values are confirmed.2603. **Wire `azure-login → get-keyvault-secrets → azure-logout`** in the job, using `id: secrets` on261 the retrieval step.2624. **Ensure `id-token: write`** is on the job, and keep the surrounding `permissions:` minimal.2635. **Place `azure-logout` correctly** — right after retrieval, unless a later step needs the live264 session, and matching any `if:` on the login.2656. **Use `@main` for the internal actions**; SHA-pin any third-party action you add. Resolve the266 real full-length SHA and its version comment — never guess one, and never leave a267 `<full-40-char-sha>` placeholder in a workflow you hand back.2687. **If the secret must reach another job or a reusable workflow**, use the mechanism above —269 re-retrieve per job, mint an App token for GitHub access, or forward the OIDC triad to the270 reusable workflow. If a reusable workflow is involved, **edit both sides**: match the caller's271 `secrets:` keys to the callee's `on.workflow_call.secrets:` declarations, and confirm each272 logging-in job carries `id-token: write`.2738. **Run the secret-hygiene checklist** before finishing.274275### Secret hygiene checklist276277Because an exposed token is a critical failure, verify each of these on any job you touch:278279- Every secret is consumed through a **step-scoped `env:`**, not inlined into a `run:` argument.280- No step `echo`s, `cat`s, prints, or writes a secret to a log, artifact, or committed file.281- The retrieval step uses `id: secrets` and pulls **only** the secrets that job actually uses — no282 speculative extras.283- `azure-logout` runs as early as possible, and the job's `permissions:` are the minimum required.284285## When AKV is needed286287| Capability | Why AKV is involved |288| ------------------------------ | ---------------------------------------------------------------- |289| Container registry push | `az acr login` (needs live session) or a registry token from AKV |290| External service integration | API keys, connection strings, third-party tokens |291| Failure / status notifications | Notification webhook URLs (e.g. Slack) retrieved from AKV |292293For pure CI capabilities with no external interaction, AKV steps are typically unnecessary — and294`azure-login` cannot succeed on a `pull_request` run from a fork. `pull_request_target` and295`workflow_run` do receive secrets, but choosing a trigger is a fork-PR access gate — out of scope296here; ask.297298## References299300- `references/actions.md` — input/output contracts for `azure-login` (including its built-in301 retry/backoff), `azure-logout`, and `get-keyvault-secrets`; plus how vault and secret names are302 supplied and the OIDC client-identity conventions.303- `Skill(bitwarden-devops-engineer:bitwarden-workflow-linter-rules)` — source of truth for all304 linted rules; invoke it for305 `permissions_exist`, `step_pinned`, `step_approved`, and anything `bwwl` checks.