Add documentation and publish it to GitHub Pages. (#18)

billnapier · web-flow · commit faab427228f4 · 2025-03-25T10:10:32.000-07:00
* Initial commit to convert markdown to GitHub pages.

* Make sure publish-pages action is reading our generated content.

* Put the path arg on the right action.

* only deploy on main

* Hook in PR preview so we can see the pages before merge.

* Fix "if" tests to get the right behavior.

* Break doc publishing up so they trigger on the right things.

* Add missing workflow

* Update permissions so workflow can publish.

* Should also need pull-request write so it can comment on the PR.

* Checkpoint to see if this is working.

* Add page artifact uploading.

* Add initial set of rule documentation, mdformat everything and add a check to keep it formatted.

* add index.md

* Update docs.
diff --git a/.github/workflows/markdown_format.yml b/.github/workflows/markdown_format.yml
@@ -0,0 +1,19 @@
+### 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: 'pipx run mdformat --check --wrap 100 .'
diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml
@@ -0,0 +1,38 @@
+name: 'Publish Docs Site'
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  pages: 'write'
+  id-token: 'write'
+
+jobs:
+  build:
+    name: "Build 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: 'Upload artifact'
+      uses: 'actions/upload-pages-artifact@v3'
+      with:
+        path: 'generated-pages'
+  deploy:
+    name: "Deploy Docs"
+    environment:
+      name: 'github-pages'
+      url: '${{ steps.deployment.outputs.page_url }}'
+    runs-on: 'ubuntu-latest'
+    needs: 'build'
+    steps:
+      - name: 'Deploy to GitHub Pages'
+        id: 'deployment'
+        uses: 'actions/deploy-pages@v4'
diff --git a/.github/workflows/publish_docs_preview.yml b/.github/workflows/publish_docs_preview.yml
@@ -0,0 +1,29 @@
+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/'
diff --git a/.github/workflows/publish_docs_preview_branch.yml b/.github/workflows/publish_docs_preview_branch.yml
@@ -0,0 +1,38 @@
+name: 'Publish Preview of Docs Site from branch'
+
+# The publish_docs_preview.yml workflow takes a PR and publishes the results to it's own branch 
+# so users can preview it.  But that git branch then needs some way to publish, so this action does that.
+
+on: 
+  push:
+    branch:
+        - gh-pages
+
+permissions:
+  pages: 'write'
+  id-token: 'write'
+
+
+jobs:
+  stage:
+    name: "Stage PR preview from branch to pages"
+    runs-on: 'ubuntu-latest'
+    steps:
+    - uses: 'actions/checkout@v4'
+      with:
+        ref: 'refs/heads/gh-pages'
+    - name: 'Upload artifact'
+      uses: 'actions/upload-pages-artifact@v3'
+      with:
+        path: '.'
+  deploy:
+    name: "Deploy PR Preview from branch to pages"
+    needs: 'stage'
+    environment:
+      name: 'gh-pages-pr-preview'
+      url: '${{ steps.deployment.outputs.page_url }}'
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Deploy to GitHub Pages'
+        id: 'deployment'
+        uses: 'actions/deploy-pages@v4'
diff --git a/README.md b/README.md
@@ -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)
diff --git a/docs/code-of-conduct.md b/docs/code-of-conduct.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/
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -7,26 +7,23 @@ We would love to accept your patches and contributions to this project.
 ### Sign our Contributor License Agreement
 
 Contributions to this project must be accompanied by a
-[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
-You (or your employer) retain the copyright to your contribution; this simply
-gives us permission to use and redistribute your contributions as part of the
-project.
+[Contributor License Agreement](https://cla.developers.google.com/about) (CLA). You (or your
+employer) retain the copyright to your contribution; this simply gives us permission to use and
+redistribute your contributions as part of the project.
 
-If you or your current employer have already signed the Google CLA (even if it
-was for a different project), you probably don't need to do it again.
+If you or your current employer have already signed the Google CLA (even if it was for a different
+project), you probably don't need to do it again.
 
-Visit <https://cla.developers.google.com/> to see your current agreements or to
-sign a new one.
+Visit <https://cla.developers.google.com/> to see your current agreements or to sign a new one.
 
 ### Review our Community Guidelines
 
-This project follows [Google's Open Source Community
-Guidelines](https://opensource.google/conduct/).
+This project follows
+[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
 
 ## Contribution process
 
 ### Code Reviews
 
-All submissions, including submissions by project members, require review. We
-use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
-for this purpose.
+All submissions, including submissions by project members, require review. We use
+[GitHub pull requests](https://docs.github.com/articles/about-pull-requests) for this purpose.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,3 @@
+# GitHub Source Solutions
+
+A collection of things we use to manage the Google Enterprise presence on GitHub.
diff --git a/docs/semgrep-rules/pull-request-target-needs-exception.md b/docs/semgrep-rules/pull-request-target-needs-exception.md
@@ -0,0 +1,12 @@
+# pull-request-target-needs-exception
+
+If you can, prefer using `pull_request` or other triggers instead of `pull_request_target`. The
+tl;dr here motivation is that workflows run from `pull_request_target` have (by default) read/write
+acesss to the repository and access to the secrets, even when run from a fork. If the workflow then
+checks out and runs the untrusted code from the PR, this is a problem.
+
+GitHub has a really good writeup of the perils here:
+https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/
+
+For now, this rule is just a warning. It will eventually require an exception to use once we get
+that process working.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# GitHub Source Solutions`
	`2`	`+`
	`3`	`+A collection of things we use to manage the Google Enterprise presence on GitHub.`