Merge branch 'master' into run_built_in_rules3

Author: billnapier

.github/workflows/action_scanning.yml

@@ -1,29 +1,22 @@
 ### Required actions to scan GitHub action workflows for security issues.
 name: 'Scan GitHub Action workflows files for security issues'
-
 on:
   pull_request: {}
-
 permissions:
   contents: 'read'
   security-events: 'write'
   actions: 'read'
-
 jobs:
   semgrep:
     name: 'semgrep-oss/scan'
     runs-on: 'ubuntu-latest'
-
     container:
       image: 'index.docker.io/semgrep/semgrep@sha256:85782eaf09692e6dfb684cd3bad87ef315775814b01f76b4d15582e4ca7c1c89' # ratchet:semgrep/semgrep
-
     # Skip any PR created by dependabot to avoid permission issues:
     if: (github.actor != 'dependabot[bot]')
-
     steps:
       - name: 'Checkout Code'
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # ratchet:actions/checkout@v4
-
       - name: 'Checkout Workflow Config'
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # ratchet:actions/checkout@v4
         env:
@@ -33,14 +26,12 @@ jobs:
           path: action_scanning
       - name: 'Run Actions semgrep scan'
         run: 'semgrep scan --sarif --config action_scanning/semgrep-rules --config "p/github-actions" >> semgrep-results-actions.sarif'
-
       - name: 'Save Actions SARIF results as artifact'
         uses: 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02' # ratchet:actions/upload-artifact@v4
 
         with:
           name: 'semgrep-scan-results-actions'
           path: 'semgrep-results-actions.sarif'
-
       - name: 'Upload Actions SARIF result to the GitHub Security Dashboard'
         uses: 'github/codeql-action/upload-sarif@1b549b9259bda1cb5ddde3b41741a82a2d15a841' # ratchet:github/codeql-action/upload-sarif@v3
         with:

.github/workflows/markdown_format.yml

@@ -0,0 +1,15 @@
+### Ensure that markdown files are properly formatted
+name: 'Check Markdown Format'
+on:
+  pull_request:
+    paths:
+      - '**.md'
+jobs:
+  mdformat:
+    name: 'mdformat'
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Checkout Code'
+        uses: 'actions/checkout@v4'
+      - name: 'Check Markdown Format'
+        run: 'tools/mdformat --check --wrap 100 .'

.github/workflows/publish_docs.yml

@@ -0,0 +1,31 @@
+name: 'Publish Docs Site'
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - '**.md'
+      - '.github/workflow/publish*'
+  workflow_dispatch:
+permissions:
+  pages: 'write'
+  id-token: 'write'
+jobs:
+  build-and-deploy:
+    name: "Build and Deploy Docs"
+    runs-on: 'ubuntu-latest'
+    steps:
+      - uses: 'actions/checkout@v4'
+      - name: 'Generate HTML from Markdown'
+        uses: 'ldeluigi/markdown-docs@latest'
+        with:
+          src: 'docs'
+          dst: 'generated-pages'
+      - name: 'Install rsync'
+        run: 'apt-get update && apt-get install -y rsync'
+      - name: 'Deploy Docs'
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: generated-pages
+          force: false
+          clean-exclude: pr-preview/

.github/workflows/publish_docs_preview.yml

@@ -0,0 +1,26 @@
+name: 'Publish Preview of Docs Site'
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+permissions:
+  contents: 'write'
+  pull-requests: 'write'
+jobs:
+  build:
+    name: "Build PR Preview Docs"
+    runs-on: 'ubuntu-latest'
+    steps:
+      - uses: 'actions/checkout@v4'
+      - name: 'Generate HTML from Markdown'
+        uses: 'ldeluigi/markdown-docs@latest'
+        with:
+          src: 'docs'
+          dst: 'generated-pages'
+      - name: 'Deploy GitHub Pages Preview'
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: './generated-pages/'

.github/workflows/semgrep_testing.yml

@@ -0,0 +1,20 @@
+### Ensure that our local testing always passes
+name: 'Run semgrep tests'
+on:
+  pull_request: {}
+permissions:
+  contents: 'read'
+  actions: 'read'
+jobs:
+  semgrep-tests:
+    name: 'Run semgrep tests'
+    runs-on: 'ubuntu-latest'
+    container:
+      image: index.docker.io/semgrep/semgrep@sha256:85782eaf09692e6dfb684cd3bad87ef315775814b01f76b4d15582e4ca7c1c89 # ratchet:semgrep/semgrep
+    # Skip any PR created by dependabot to avoid permission issues:
+    if: (github.actor != 'dependabot[bot]')
+    steps:
+      - name: 'Checkout Code'
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # ratchet:actions/checkout@v4
+      - name: 'Run Actions semgrep scan'
+        run: 'semgrep --test --config semgrep-rules semgrep-tests'

.github/workflows/semver_testing.yml

@@ -0,0 +1,16 @@
+### Ensure that Yaml files are properly formatted
+name: 'Check Yaml Format'
+on:
+  pull_request:
+    paths:
+      - '**.yml'
+      - '**.yaml'
+jobs:
+  yamlfmt:
+    name: 'yamlfmt'
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Checkout Code'
+        uses: 'actions/checkout@v4'
+      - name: 'Check Yaml Format'
+        run: 'tools/yamlfmt --lint .'

.github/workflows/yaml_format.yml

@@ -0,0 +1,3 @@
+formatter:
+  max_line_length: 100
+  trim_trailing_whitespace: true

.yamlfmt

@@ -1,5 +1,7 @@
 # The Home of GitHub Source Solutions
 
-This is where the team that manages GitHub for Google places things (like required workflows) to use across the enterprise.
+This is where the team that manages GitHub for Google places things (like required workflows) to use
+across the enterprise.
 
-We also own a number of other repositories.  See them [here](https://github.com/topics/github-source-solutions)
+We also own a number of other repositories. See them
+[here](https://github.com/topics/github-source-solutions)

README.md

@@ -2,94 +2,82 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of
-experience, education, socio-economic status, nationality, personal appearance,
-race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers
+pledge to making participation in our project and our community a harassment-free experience for
+everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level
+of experience, education, socio-economic status, nationality, personal appearance, race, religion,
+or sexual identity and orientation.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
-include:
+Examples of behavior that contributes to creating a positive environment include:
 
-*   Using welcoming and inclusive language
-*   Being respectful of differing viewpoints and experiences
-*   Gracefully accepting constructive criticism
-*   Focusing on what is best for the community
-*   Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-*   The use of sexualized language or imagery and unwelcome sexual attention or
-    advances
-*   Trolling, insulting/derogatory comments, and personal or political attacks
-*   Public or private harassment
-*   Publishing others' private information, such as a physical or electronic
-    address, without explicit permission
-*   Disrespecting the community's time by sending spam or other unsolicited
-    commercial messages
-*   Other conduct which could reasonably be considered inappropriate in a
-    professional setting
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit
+  permission
+- Disrespecting the community's time by sending spam or other unsolicited commercial messages
+- Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are
+expected to take appropriate and fair corrective action in response to any instances of unacceptable
+behavior.
 
-Project maintainers have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, or to ban temporarily or permanently any
-contributor for other behaviors that they deem inappropriate, threatening,
-offensive, or harmful.
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits,
+code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or
+to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
 
 ## Scope
 
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
+This Code of Conduct applies both within project spaces and in public spaces when an individual is
+representing the project or its community. Examples of representing a project or community include
+using an official project e-mail address, posting via an official social media account, or acting as
+an appointed representative at an online or offline event. Representation of a project may be
 further defined and clarified by project maintainers.
 
-This Code of Conduct also applies outside the project spaces when the Project
-Steward has a reasonable belief that an individual's behavior may have a
-negative impact on the project or its community.
+This Code of Conduct also applies outside the project spaces when the Project Steward has a
+reasonable belief that an individual's behavior may have a negative impact on the project or its
+community.
 
 ## Conflict Resolution
 
-We do not believe that all conflict is bad; healthy debate and disagreement
-often yield positive results. However, it is never okay to be disrespectful or
-to engage in behavior that violates the project’s code of conduct.
-
-If you see someone violating the code of conduct, you are encouraged to address
-the behavior directly with those involved. Many issues can be resolved quickly
-and easily, and this gives people more control over the outcome of their
-dispute. If you are unable to resolve the matter for any reason, or if the
-behavior is threatening or harassing, report it. We are dedicated to providing
-an environment where participants feel welcome and safe.
-
-Reports should be directed to *[PROJECT STEWARD NAME(s) AND EMAIL(s)]*, the
-Project Steward(s) for *[PROJECT NAME]*. It is the Project Steward’s duty to
-receive and address reported violations of the code of conduct. They will then
-work with a committee consisting of representatives from the Open Source
-Programs Office and the Google Open Source Strategy team. If for any reason you
-are uncomfortable reaching out to the Project Steward, please email
-opensource@google.com.
-
-We will investigate every complaint, but you may not receive a direct response.
-We will use our discretion in determining when and how to follow up on reported
-incidents, which may range from not taking action to permanent expulsion from
-the project and project-sponsored spaces. We will notify the accused of the
-report and provide them an opportunity to discuss it before any action is taken.
-The identity of the reporter will be omitted from the details of the report
-supplied to the accused. In potentially harmful situations, such as ongoing
-harassment or threats to anyone's safety, we may take action without notice.
+We do not believe that all conflict is bad; healthy debate and disagreement often yield positive
+results. However, it is never okay to be disrespectful or to engage in behavior that violates the
+project’s code of conduct.
+
+If you see someone violating the code of conduct, you are encouraged to address the behavior
+directly with those involved. Many issues can be resolved quickly and easily, and this gives people
+more control over the outcome of their dispute. If you are unable to resolve the matter for any
+reason, or if the behavior is threatening or harassing, report it. We are dedicated to providing an
+environment where participants feel welcome and safe.
+
+Reports should be directed to *[PROJECT STEWARD NAME(s) AND EMAIL(s)]*, the Project Steward(s) for
+*[PROJECT NAME]*. It is the Project Steward’s duty to receive and address reported violations of the
+code of conduct. They will then work with a committee consisting of representatives from the Open
+Source Programs Office and the Google Open Source Strategy team. If for any reason you are
+uncomfortable reaching out to the Project Steward, please email opensource@google.com.
+
+We will investigate every complaint, but you may not receive a direct response. We will use our
+discretion in determining when and how to follow up on reported incidents, which may range from not
+taking action to permanent expulsion from the project and project-sponsored spaces. We will notify
+the accused of the report and provide them an opportunity to discuss it before any action is taken.
+The identity of the reporter will be omitted from the details of the report supplied to the accused.
+In potentially harmful situations, such as ongoing harassment or threats to anyone's safety, we may
+take action without notice.
 
 ## Attribution
 
-This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
-available at
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at
 https://www.contributor-covenant.org/version/1/4/code-of-conduct/