bitwarden_workflow_linter 1.3.2__tar.gz → 1.3.4__tar.gz

bitwarden_workflow_linter-1.3.4/.github/copilot-instructions.md

@@ -0,0 +1,142 @@
+# Bitwarden Workflow Linter - Copilot Instructions
+
+## Repository Overview
+
+**Bitwarden Workflow Linter** is an extensible Python CLI tool that enforces opinionated organization-specific GitHub Action standards.
+
+**CRITICAL UNDERSTANDING**: This tool generates and publishes **rules that are consumed across ALL Bitwarden repositories**. Changes to rules affect the entire Bitwarden organization's CI/CD pipelines, not just this repository. Rules are distributed via PyPI and consumed by repositories through the [composite Action](https://github.com/bitwarden/gh-actions/tree/main/lint-workflow).
+
+### High-Level Details
+
+-   **Type**: Python CLI application and library (~86 Python files)
+-   **Language**: Python 3.13.5 (minimum 3.11 supported)
+-   **Package Manager**: pipenv for dependencies, hatch for building/publishing
+-   **Distribution**: Published to PyPI as `bitwarden_workflow_linter`
+-   **CLI Command**: `bwwl`
+-   **Organizational Impact**: Rules affect CI/CD across entire Bitwarden codebase
+
+## Build & Development Setup
+
+### Essential Commands (Always run in this order)
+
+```bash
+# Setup (REQUIRED before any development work)
+pipenv install --dev
+pipenv shell
+pip install -e .
+
+# Testing (ALWAYS run before submitting changes)
+pytest tests --cov=src
+
+# Code quality (REQUIRED before merging to main)
+black .
+pylint --rcfile pylintrc src/ tests/
+
+# Type checking (Linux only)
+pytype src
+```
+
+### Task Runner Shortcuts
+
+-   `task test:cov` - Run tests with coverage
+-   `task fmt` - Format code with black
+-   `task lint` - Run pylint
+
+## Key Project Structure
+
+**Rules Location**: `src/bitwarden_workflow_linter/rules/` - All linting rules
+**Rule Base Class**: `src/bitwarden_workflow_linter/rule.py` - Extend this for new rules
+**CLI Entry**: `src/bitwarden_workflow_linter/cli.py:main()`
+**Configuration**:
+
+-   `settings.yaml` (local overrides)
+-   `src/bitwarden_workflow_linter/default_settings.yaml` (defaults)
+
+## Rule Development - Organization-Wide Impact
+
+**CRITICAL**: Rules developed here are distributed to and enforced across ALL Bitwarden repositories. Every rule change has organization-wide impact.
+
+### Rule Distribution Flow
+
+1. Rules developed/tested in this repository
+2. Published to PyPI as `bitwarden_workflow_linter`
+3. Consumed by all Bitwarden repositories via gh-actions/lint-workflow
+4. Enforced in CI/CD pipelines organization-wide
+5. Rule failures can block deployments across hundreds of repositories
+
+### Rule Rollout Process (MANDATORY)
+
+**Before making ANY rule changes, read `RULE_ROLLOUT.md`** - documents the careful process for organization-wide deployment.
+
+**Key principles:**
+
+-   **Gradual Rollout**: New rules start as `warning`, then upgrade to `error`
+-   **Impact Assessment**: Test against representative workflows before activation
+-   **Communication**: Coordinate with teams before deploying breaking changes
+
+### Adding New Rules
+
+1. **CRITICAL**: Rules must be implemented, tested, and merged to main BEFORE activation
+2. **CRITICAL**: Follow `RULE_ROLLOUT.md` process to avoid breaking organization CI
+3. Extend `Rule` base class in `src/bitwarden_workflow_linter/rule.py`
+4. Place in `src/bitwarden_workflow_linter/rules/`
+5. Must define: `message`, `on_fail`, `compatibility`, `settings`, and `fn()` method
+6. Add comprehensive tests with 100% coverage
+7. Start with `warning` level, upgrade to `error` after validation period
+8. After release, activate by adding to `settings.yaml` and `default_settings.yaml`
+
+### Rule Impact Levels
+
+-   **ERROR Level**: Block CI/CD across all Bitwarden repositories - handle with extreme care
+-   **WARNING Level**: Generate notifications but don't block - safer for initial rollout
+
+## Security Considerations
+
+### Critical Security Rules (Organization-Wide)
+
+-   **Action Pinning**: `step_pinned.py` enforces SHA pinning (not tags) at ERROR level across all repos
+    -   Example: `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2`
+-   **Approved Actions**: `step_approved.py` enforces use of pre-approved actions only
+-   **Permissions**: `permissions_exist.py` enforces explicit permissions in workflows
+-   **PR Target Protection**: `check_pr_target.py` prevents dangerous `pull_request_target` usage
+
+**Security rule changes affect organization-wide security posture - always coordinate with security team.**
+
+## Critical Issues & Solutions
+
+### Rule Activation Order
+
+-   **ERROR**: Activating rules before release causes import errors across all Bitwarden repositories
+-   **SOLUTION**: Always merge rule implementation first, then activate after PyPI release
+
+### Organization-Wide Impact
+
+-   **ERROR**: Deploying ERROR-level rules without testing breaks CI across hundreds of repositories
+-   **SOLUTION**: Start with WARNING level, test extensively, coordinate rollout via `RULE_ROLLOUT.md`
+
+### Testing Best Practices
+
+-   Tests change directories to avoid repo-specific paths
+-   Use `default_settings.yaml` instead of repo `settings.yaml` in tests
+-   Run with `--strict` flag to catch warnings as errors
+-   Test rules against diverse workflow patterns from different Bitwarden repositories
+
+## Agent Instructions
+
+**Trust these instructions first** - only search for additional information if incomplete or incorrect.
+
+**CRITICAL AWARENESS**: This repository's rules are consumed across ALL Bitwarden repositories. Every change has organization-wide impact.
+
+**Required sequence for changes:**
+
+1. **Read `RULE_ROLLOUT.md` if working with rules** - understand organization-wide impact
+2. `pipenv shell && pip install -e .`
+3. `pytest tests --cov=src`
+4. `black . && pylint --rcfile pylintrc src/ tests/`
+5. Test CLI: `bwwl lint --files tests/fixtures`
+
+**For rule development:**
+
+-   Rules affect hundreds of other Bitwarden repositories
+-   Start with WARNING level, coordinate rollout, upgrade to ERROR only after validation
+-   **Never deploy ERROR-level rules without extensive testing and coordination**

{bitwarden_workflow_linter-1.3.2 → bitwarden_workflow_linter-1.3.4}/.github/workflows/bwwl_operations.yml

@@ -4,15 +4,19 @@ on:
   workflow_dispatch:
     inputs:
       operation:
-        description: 'Operation to perform. ex: update, add'
+        description: "Operation to perform. ex: update, add"
         required: true
         type: string
       action:
-        description: 'Single action to add. ex: actions/checkout'
+        description: "Single action to add. ex: actions/checkout"
+        required: false
+        type: string
+      artifact:
+        description: "Artifact reference (JIRA ticket, business reason, etc) for the new action."
         required: false
         type: string
   schedule:
-  - cron: '0 0 * * 1'
+    - cron: "0 0 * * 1"
 
 jobs:
   actions-operation:
@@ -24,10 +28,15 @@ jobs:
       pull-requests: write
     env:
       _ACTION: ${{ inputs.action }}
+      _ARTIFACT: ${{ inputs.artifact }}
     steps:
-      -  name: Check for action input
-         if: ${{ inputs.operation == 'add' && !env._ACTION }}
-         run: echo "Action input is required for operation 'add'" && exit 1
+      - name: Check for action input
+        if: ${{ inputs.operation == 'add' && !env._ACTION }}
+        run: echo "Action input is required for operation 'add'" && exit 1
+
+      - name: Check for artifact reference
+        if: ${{ inputs.operation == 'add' && !env._ARTIFACT }}
+        run: echo "Artifact reference is required for operation 'add'" && exit 1
 
       - name: Log in to Azure
         uses: bitwarden/gh-actions/azure-login@main
@@ -55,7 +64,7 @@ jobs:
         uses: bitwarden/gh-actions/azure-logout@main
 
       - name: Checkout Branch
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Import GPG key
         uses: crazy-max/ghaction-import-gpg@e89d40939c28e39f97cf32126055eeae86ba74ec # v6.3.0
@@ -73,7 +82,7 @@ jobs:
       - name: Set up Python 3.12
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install bwwl binary
         run: python -m pip install --upgrade bitwarden_workflow_linter
@@ -134,6 +143,7 @@ jobs:
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           TITLE: "Update/Add bwwl approved actions${{ inputs.operation == 'add' && env._ACTION != '' && format(' for {0}', env._ACTION) || '' }}"
+          ARTIFACT: "${{ inputs.operation == 'add' && format('\n    ## Artifact Reference\n    {0}\n', env._ARTIFACT) || '' }}"
         run: |
           PR_URL=$(gh pr create --title "$TITLE" \
             --base "main" \
@@ -148,6 +158,9 @@ jobs:
               - [ ] Build/deploy pipeline (DevOps)
               - [ ] Other
 
+              ## Initiated by
+              ${{ github.actor }}
+              $ARTIFACT
               ## Description
               - This PR updates the approved actions for the Bitwarden Workflow Linter.")
-          echo "pr_number=${PR_URL##*/}" >> $GITHUB_OUTPUT
+          echo "### PR created: $PR_URL" >> $GITHUB_STEP_SUMMARY

{bitwarden_workflow_linter-1.3.2 → bitwarden_workflow_linter-1.3.4}/.github/workflows/cd.yml

@@ -64,7 +64,7 @@ jobs:
           private-key: ${{ steps.get-kv-secrets.outputs.BW-GHAPP-KEY }}
 
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
           token: ${{ steps.app-token.outputs.token }}
@@ -125,10 +125,10 @@ jobs:
       contents: write
     steps:
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Create GitHub release
-        uses: ncipollo/release-action@440c8c1cb0ed28b9f43e4d1d670870f059653174 # v1.16.0
+        uses: ncipollo/release-action@bcfe5470707e8832e12347755757cec0eb3c22af # v1.18.0
         with:
           commit: ${{ github.sha }}
           tag: v${{ needs.version-bump.outputs.version }}
@@ -145,7 +145,7 @@ jobs:
       id-token: write
     steps:
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
           ref: ${{ needs.version-bump.outputs.commit_hash }}

{bitwarden_workflow_linter-1.3.2 → bitwarden_workflow_linter-1.3.4}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Check out repo
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0

{bitwarden_workflow_linter-1.3.2 → bitwarden_workflow_linter-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitwarden_workflow_linter
-Version: 1.3.2
+Version: 1.3.4
 Summary: Custom GitHub Action Workflow Linter
 Project-URL: Homepage, https://github.com/bitwarden/workflow-linter
 Project-URL: Issues, https://github.com/bitwarden/workflow-linter/issues

{bitwarden_workflow_linter-1.3.2 → bitwarden_workflow_linter-1.3.4}/src/bitwarden_workflow_linter/__about__.py

@@ -1,3 +1,3 @@
 """Metadata for Workflow Linter."""
 
-__version__ = "1.3.2"
+__version__ = "1.3.4"