bitwarden-workflow-linter-rules
Reference for all Bitwarden workflow linter (bwwl) rules. Covers all 10 linter rules split into two categories: mechanical rules that can be applied automatically (name_capitalized, permissions_exist, pinned_job_runner, step_pinned, underscore_outputs, job_environment_prefix, check_pr_target) and judgment rules requiring user input (name_exists, step_approved, run_actionlint). Use the workflow-audit skill to run the linter and report findings, and the workflow-fix skill to apply fixes. <example> User: What does the step_pinned rule check for? Action: Consult this skill for the rule definition and fix procedure </example> <example> User: How do I fix a permissions_exist finding? Action: Consult this skill for the fix procedure </example>
How do I install this agent skill?
npx skills add https://github.com/bitwarden/ai-plugins --skill bitwarden-workflow-linter-rulesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a reference for Bitwarden workflow linter rules. It is generally safe but processes external GitHub Action workflow files which could contain malicious content designed to influence the agent (Indirect Prompt Injection). It also involves the use of the GitHub CLI to resolve commit SHAs for external actions.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Mechanical Rules — apply automatically
name_capitalized
- Trigger: A workflow-level or job-level
name:value does not start with a capital letter. - Fix: Capitalize the first character of the name value. Do not change anything else.
permissions_exist
- Trigger: A workflow or job is missing an explicit
permissions:key. - Fix: Add
permissions: {}at the workflow level if all jobs are missing it, or at the individual job level if only some jobs are missing it. Prefer job-level permissions.
pinned_job_runner
- Trigger: A job's
runs-on:uses an unpinned label. - Fix: Replace with the current pinned equivalent:
ubuntu-latest→ubuntu-24.04windows-latest→windows-2022macos-latest→macos-26
step_pinned
Bitwarden enforces two distinct pinning requirements depending on who owns the action. Steps with no uses: field and local actions (starting with ./) are skipped entirely.
-
Trigger (internal actions): A
uses:reference starting withbitwarden/is not pinned to@main. Exception: references of the formbitwarden/sm-action[/path]@<any-ref>are compliant at any ref and never trigger this rule. -
Trigger (external actions): A
uses:reference not starting withbitwarden/is not pinned to a full 40-character commit SHA, or is missing an inline version comment. -
Fix (internal actions):
- Change the ref to
@main(e.g.,bitwarden/gh-actions/azure-login@v1→bitwarden/gh-actions/azure-login@main) - Do not resolve a SHA —
@mainis the required and compliant state.
- Change the ref to
-
Fix (external actions):
- Resolve the correct commit SHA via the GitHub API:
gh api repos/{owner}/{repo}/commits/{ref} --jq '.sha' - Show the SHA and a verification link (
https://github.com/{owner}/{repo}/commit/{sha}) to the user before applying. - Wait for the user to confirm the SHA. If they provide a different SHA, use that instead.
- Replace the
uses:value with{action}@{sha}and add a comment with the original tag:# {original-ref}
- Example:
uses: actions/checkout@v4→uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
- Resolve the correct commit SHA via the GitHub API:
underscore_outputs
- Trigger: A multi-word output name in a
$GITHUB_OUTPUTwrite oroutputs:block uses hyphens or camelCase instead of underscores. - Fix: Rename the output key to use underscores. Update all references to that output within the same file.
job_environment_prefix
- Trigger: An environment variable name at the job level does not follow
SCREAMING_SNAKE_CASE. - Fix: Rename to
SCREAMING_SNAKE_CASEand update all usages within the job.
check_pr_target
- Trigger: A workflow using
pull_request_targethas jobs not restricted to the default branch. - Fix: Add a condition to the affected jobs:
if: github.ref == 'refs/heads/<default-branch>'. Determine the repo's default branch rather than assumingmain. If the job already has anif:condition, combine with&&(e.g.,if: <existing-condition> && github.ref == 'refs/heads/<default-branch>').
Judgment Rules — pause and ask the user
name_exists
- Trigger: A workflow or job is missing a
name:key entirely. - Fix: Ask the user what name to use, then add a
name:key at the correct level with a capitalized value.
step_approved
- Trigger: A step's
uses:references an action not on the Bitwarden approved actions list. - Options to present to the user:
- Add to approved list — if the action is legitimate and has been reviewed and approved, add it to
bitwarden/workflow-linter's approved actions config. - Replace — swap with an approved alternative that provides the same functionality.
- Remove — delete the step if it is not essential.
- Add to approved list — if the action is legitimate and has been reviewed and approved, add it to
- Do not make this change automatically. Show the unapproved action name, ask which option the user wants, then act.
run_actionlint (complex findings)
- Trigger:
actionlintreports an error that is not a simple formatting issue (e.g., type mismatches in expressions, invalid context references, shell script errors). - Action: Show the finding verbatim, suggest a fix based on actionlint's message, and ask the user to confirm before applying.
- Simple actionlint findings (e.g.,
shellcheckstyle warnings with a clear single-line fix) may be applied automatically.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/bitwarden/ai-plugins/bitwarden-workflow-linter-rules">View bitwarden-workflow-linter-rules on skillZs</a>