diff --git a/.github/workflows/markdown_format.yml b/.github/workflows/markdown_format.yml new file mode 100644 index 0000000..7ec56eb --- /dev/null +++ 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 .' \ No newline at end of file diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml new file mode 100644 index 0000000..6d814a2 --- /dev/null +++ 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' \ No newline at end of file diff --git a/.github/workflows/publish_docs_preview.yml b/.github/workflows/publish_docs_preview.yml new file mode 100644 index 0000000..b1e1d4d --- /dev/null +++ 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/' \ No newline at end of file diff --git a/.github/workflows/publish_docs_preview_branch.yml b/.github/workflows/publish_docs_preview_branch.yml new file mode 100644 index 0000000..32e5032 --- /dev/null +++ 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 index 2679468..944313d 100644 --- 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) \ No newline at end of file +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 index 6070ae1..38cfd3c 100644 --- 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 index 8956a61..0e511d2 100644 --- 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 to see your current agreements or to -sign a new one. +Visit 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 new file mode 100644 index 0000000..be22103 --- /dev/null +++ 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 new file mode 100644 index 0000000..5de6b4b --- /dev/null +++ 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.