Index of every page on this site: llms.txt
All skills
bitwarden avatar

/bitwarden-workflow-linter-rules

@a11c77b official
by bitwardenbitwarden/ai-plugins165 stars
27
Run it yourself

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>

Use this Skill: https://skilld.dev/gh/bitwarden/ai-plugins/bitwarden-workflow-linter-rules

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈195 tokens for metadata: the name and description. ≈1.1k when used: this file.

Description uses 9.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈780 characters, or 9.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.04
    • windows-latest → windows-2022
    • macos-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 with bitwarden/ is not pinned to @main. Exception: references of the form bitwarden/sm-action[/path]@<any-ref> are compliant at any ref and never trigger this rule.

  • Trigger (external actions): A uses: reference not starting with bitwarden/ 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 — @main is the required and compliant state.
  • Fix (external actions):

    1. Resolve the correct commit SHA via the GitHub API: gh api repos/{owner}/{repo}/commits/{ref} --jq '.sha'
    2. Show the SHA and a verification link (https://github.com/{owner}/{repo}/commit/{sha}) to the user before applying.
    3. Wait for the user to confirm the SHA. If they provide a different SHA, use that instead.
    4. 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

underscore_outputs

  • Trigger: A multi-word output name in a $GITHUB_OUTPUT write or outputs: 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_CASE and update all usages within the job.

check_pr_target

  • Trigger: A workflow using pull_request_target has 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 assuming main. If the job already has an if: 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:
    1. 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.
    2. Replace — swap with an approved alternative that provides the same functionality.
    3. Remove — delete the step if it is not essential.
  • Do not make this change automatically. Show the unapproved action name, ask which option the user wants, then act.

run_actionlint (complex findings)

  • Trigger: actionlint reports 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., shellcheck style warnings with a clear single-line fix) may be applied automatically.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts10d3 checks · Risk SAFE
  • Gen Agent Trust Hub10d

    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.

  • Socket10d

    No alerts

  • Snyk10d

    Risk: LOW · No issues

Signed by skilld at a11c77b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago
  • bitwarden
  • github-actions
  • workflow-linter
  • ci-cd
  • linting
  • yaml
  • github
  • automation

README badge

README badge for bitwarden/ai-plugins/bitwarden-workflow-linter-rules

Reference documentation for Bitwarden's workflow linter rules, covering 10 linting checks split between mechanical rules (name capitalization, permissions, job runner pinning, step pinning, output naming, environment variables, pull_request_target safety) and judgment rules requiring user confirmation (unapproved actions, missing names, complex actionlint findings). Use this skill to understand what each rule checks for and how to fix violations.

Generated from the current SKILL.md.

What's the difference between mechanical and judgment rules?
Mechanical rules (name_capitalized, permissions_exist, pinned_job_runner, step_pinned, underscore_outputs, job_environment_prefix, check_pr_target) can be applied automatically. Judgment rules (name_exists, step_approved, run_actionlint) require user input or confirmation before changes are made.
How do I fix an unpinned external action?
Resolve the correct commit SHA via the GitHub API, show it to the user for verification, wait for confirmation, then replace the uses value with the SHA and add a comment with the original tag (e.g., `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4`).
What runner versions does the pinned_job_runner rule enforce?
The rule requires ubuntu-24.04 (not ubuntu-latest), windows-2022 (not windows-latest), and macos-14 (not macos-latest).
Are internal Bitwarden actions pinned differently than external actions?
Yes. Internal actions starting with `bitwarden/` must be pinned to `@main`, while external actions must be pinned to a full 40-character commit SHA. The exception is `bitwarden/sm-action` which is compliant at any ref.
How do I use this skill with the workflow-audit and workflow-fix skills?
This skill is a reference for all linter rules and their fixes. Use the workflow-audit skill to run the linter and identify findings, then consult this skill for fix procedures, and use the workflow-fix skill to apply the fixes.

Generated from the current SKILL.md. These answers refresh after source changes.