Additional updates to docs (#2)

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# https://help.github.com/articles/about-codeowners/
+* @azure/psrule-rules-azure

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## PR Summary
+
+<!-- summarize your PR between here and the checklist -->
+
+## PR Checklist
+
+- [ ] PR has a meaningful title
+- [ ] Summarized changes
+- [ ] Change is not breaking
+- [ ] This PR is ready to merge and is not **Work in Progress**

.github/dependabot.yml

@@ -0,0 +1,15 @@
+#
+# Dependabot configuration
+#
+
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+
+# Maintain dependencies for GitHub Actions
+- package-ecosystem: 'github-actions'
+  directory: '/'
+  schedule:
+    interval: 'daily'

.github/workflows/ms-analyze.yaml

@@ -0,0 +1,36 @@
+#
+# Analyze repository with PSRule
+#
+
+# Note:
+# This workflow is designed to run only in Azure/PSRule.Rules.Azure-governed.
+# You can safely deleted this file if you have templated this repository to your GitHub organization.
+
+# For PSRule documentation see:
+# https://aka.ms/ps-rule
+
+# For action details see:
+# https://aka.ms/ps-rule-action
+
+name: Analyze repository
+
+# Run for main or PRs against main
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  analyze:
+    name: Analyze repository
+    runs-on: ubuntu-latest
+    if: github.repository == 'Azure/PSRule.Rules.Azure-governed'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Run PSRule analysis
+        uses: microsoft/ps-rule@v2.7.0
+        with:
+          modules: PSRule.Rules.MSFT.OSS

.gitignore

@@ -0,0 +1,4 @@
+
+reports/
+out/
+.vs/

.markdownlint.json

@@ -0,0 +1,67 @@
+{
+  "default": true,
+  "header-increment": true,
+  "first-header-h1": {
+    "level": 1
+  },
+  "header-style": {
+    "style": "atx"
+  },
+  "ul-style": {
+    "style": "dash"
+  },
+  "list-indent": true,
+  "ul-start-left": true,
+  "ul-indent": {
+    "indent": 2
+  },
+  "no-trailing-spaces": true,
+  "no-hard-tabs": true,
+  "no-reversed-links": true,
+  "no-multiple-blanks": true,
+  "line-length": {
+    "line_length": 150,
+    "code_blocks": false,
+    "tables": false,
+    "headers": true
+  },
+  "commands-show-output": true,
+  "no-missing-space-atx": true,
+  "no-multiple-space-atx": true,
+  "no-missing-space-closed-atx": true,
+  "no-multiple-space-closed-atx": true,
+  "blanks-around-headers": true,
+  "header-start-left": true,
+  "no-duplicate-header": true,
+  "single-h1": true,
+  "no-trailing-punctuation": {
+    "punctuation": ".,;:!"
+  },
+  "no-multiple-space-blockquote": true,
+  "no-blanks-blockquote": true,
+  "ol-prefix": {
+    "style": "one_or_ordered"
+  },
+  "list-marker-space": true,
+  "blanks-around-fences": true,
+  "blanks-around-lists": true,
+  "no-bare-urls": true,
+  "hr-style": {
+    "style": "---"
+  },
+  "no-emphasis-as-header": true,
+  "no-space-in-emphasis": true,
+  "no-space-in-code": true,
+  "no-space-in-links": true,
+  "fenced-code-language": false,
+  "first-line-h1": false,
+  "no-empty-links": true,
+  "proper-names": {
+    "names": [
+      "PowerShell",
+      "JavaScript"
+    ],
+    "code_blocks": false
+  },
+  "no-alt-text": true
+}

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "bewhite.psrule-vscode-preview",
+    "ms-azuretools.vscode-bicep"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "files.associations": {
+    "**/.pipelines/**/*.yaml": "azure-pipelines",
+    "**/pipelines/ado/**/*.yaml": "azure-pipelines"
+  },
+  "files.insertFinalNewline": true,
+  "editor.tabSize": 2,
+  "editor.insertSpaces": true,
+  "editor.detectIndentation": false,
+  "editor.formatOnSave": true,
+  "yaml.schemas": {
+    "https://json.schemastore.org/github-workflow.json": "**/.github/workflows/*.yaml"
+  }
+}

.vscode/tasks.json

@@ -0,0 +1,19 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=733558
+  // for the documentation about the tasks.json format
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "PSRule",
+      "problemMatcher": [
+        "$PSRule"
+      ],
+      "label": "PSRule: Run analysis",
+      "presentation": {
+        "focus": false,
+        "panel": "dedicated",
+        "clear": true
+      }
+    }
+  ]
+}

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to PSRule for Azure
+# Contributing to PSRule for Azure governed modules
 
 Welcome, and thank you for your interest in contributing to PSRule!
 
@@ -14,7 +14,7 @@ The goal of this document is to provide a high-level overview of how you can get
 This project welcomes contributions and suggestions. Most contributions require you to
 agree to a Contributor License Agreement (CLA) declaring that you have the right to,
 and actually do, grant us the rights to use your contribution. For details, visit
-https://cla.microsoft.com.
+<https://cla.microsoft.com>.
 
 When you submit a pull request, a CLA-bot will automatically determine whether you need
 to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
@@ -35,13 +35,13 @@ Here's how you can make reporting your issue as effective as possible.
 
 ### Look for an existing issue
 
-Before you create a new issue, please do a search in [open issues][issues] to see if the issue or feature request has already been filed.
+Before you create a new issue, please do a search in [open issues][issue] to see if the issue or feature request has already been filed.
 
 If you find your issue already exists,
 make relevant comments and add your [reaction](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments).
 Use a reaction in place of a "+1" comment:
 
-* 👍 - upvote
+- 👍 - upvote
 
 ### Intro to Git and GitHub
 
@@ -55,7 +55,7 @@ Check out the links below to get started.
   - [Fork a repo][github-fork].
   - [About Pull Requests][github-pr].
 
-## Thank You!
+## Thank You
 
 Your contributions to open source, large or small, make great projects like this possible.
 Thank you for taking the time to contribute.
@@ -65,4 +65,4 @@ Thank you for taking the time to contribute.
 [github-signup]: https://github.com/signup/free
 [github-fork]: https://help.github.com/en/github/getting-started-with-github/fork-a-repo
 [github-pr]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
-[github-pr-create]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork
+[issue]: https://github.com/Azure/PSRule.Rules.Azure-governed/issues

README.md

@@ -1,27 +1,46 @@
-# PSRule for Azure governed modules
+# Azure Governed Pipelines
 
 **In development**
 
-This repository contains a sample code you can use to create your own Bicep module repository.
-To learn more about PSRule for Azure, see https://aka.ms/ps-rule-azure.
+This repository contains sample code you can use to create your own governed pipelines for deploying Azure solutions.
+To learn more about PSRule for Azure, see <https://aka.ms/ps-rule-azure>.
 
 [![Use this template](https://img.shields.io/static/v1?label=GitHub&message=Use%20this%20template&logo=github&color=007acc)](https://github.com/Azure/PSRule.Rules.Azure-governed/generate)
 
-<!-- ## What's included?
+## Overview
 
-This repository includes:
+Building enterprise scale pipelines can be challenging.
+Without a standard approach, pipelines can become complex and difficult to maintain.
+Governed pipelines provides a set of patterns to help you build and maintain pipelines for deploying Azure solutions.
+
+- **Who should consider using governed pipelines?** &mdash; Any organzation that need to scale one or two pipelines to many.
+- **Why use governed pipelines?** &mdash; A central set of governed pipelines allows you to managed quality and security across projects or teams.
+- **What systems are supported?** &mdash; In the current interation governed pipelines support Azure Pipelines.
+  In the future we plan to add support for GitHub Actions.
+
+## How do they work?
+
+Governed Pipelines allow an organization to enforce controls within deployment pipelines by extending on built-in features of Azure and GitHub.
+
+Pipelines **must** prove they have extended from a secure pipeline that enforces an organization's DevSecOps requirements.
+
+- When a pipeline extends from a governed pipeline it is entitled to use credentials with permissions to deploy to Azure.
+- If the pipeline does not use a governed pipeline the credentials are not provides to the pipeline and deployment is blocked.
+
+The implementation for Azure Piplines and GitHub Action is slightly different as follows:
+
+- **Azure Pipelines** &mdash; [Security through templates][1] requires a specific pipeline template to be used.
+- **GitHub Actions (available in the future)** &mdash; [Open ID Connect with reusable workflows][3] requires a specific workflow template to be used.
+
+  [1]: https://learn.microsoft.com/azure/devops/pipelines/security/templates?view=azure-devops
+  [3]: https://docs.github.com/enterprise-cloud@latest/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows
+
+## Getting started
+
+To get started, please check out our consumer guide for:
+
+- [Azure Pipelines](docs/consumer-azure-pipelines.md)
 
-- **Azure Templates** &mdash; Starter Azure Resource Manager (ARM) templates and parameter files.
-  - Use the files in the `template/` folder if you are using ARM templates to deploy resources.
-- **Azure Bicep** &mdash; Starter Azure Bicep deployments and test files.
-  - Use the files in the `bicep/` folder if you are using Bicep deployments and modules to deploy resources.
-- **GitHub Actions** &mdash; Starter workflow for checking Azure Infrastructure as Code (IaC).
-  - Use the files in the `.github/workflows/` to check your Azure IaC with GitHub Actions.
-  - The `ms-analyze.yaml` file can be ignore or removed as this will not execute outside this repository.
-- **Azure Pipelines** &mdash; Coming soon.
-- **Custom rules** &mdash; Example custom rules that enforce organization specific requirements.
-  - Use the files in the `.ps-rule/` folder to configure custom rules. -->
-<!-- 
 ## Support
 
 This project uses GitHub Issues to track bugs and feature requests.
@@ -30,7 +49,10 @@ Please search the existing issues before filing new issues to avoid duplicates.
 - For new issues, file your bug or feature request as a new [issue].
 - For help, discussion, and support questions about using this project, join or start a [discussion].
 
-Support for this project/ product is limited to the resources listed above. -->
+Support for this project/ product is limited to the resources listed above.
+
+  [issue]: https://github.com/Azure/PSRule.Rules.Azure-governed/issues
+  [discussion]: https://github.com/Azure/PSRule.Rules.Azure-governed/discussion
 
 ## Contributing
 
@@ -46,7 +68,7 @@ or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any addi
 ## Maintainers
 
 - [Bernie White](https://github.com/BernieWhite)
-- [Armaan Mcleod](https://github.com/ArmaanMcleod)
+- [Sam Bell](https://github.com/ms-sambell)
 
 ## License
 
@@ -58,6 +80,3 @@ This project may contain trademarks or logos for projects, products, or services
 Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
 Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
 Any use of third-party trademarks or logos are subject to those third-party's policies.
-
-[issue]: https://github.com/Azure/PSRule.Rules.Azure-governed/issues
-[discussion]: https://github.com/Azure/PSRule.Rules.Azure-governed/discussions

docs/consumer-azure-pipelines.md

@@ -0,0 +1,11 @@
+# Governed Pipelines consumer guide for Azure Pipelines
+
+**In development**
+
+## Setup in Azure DevOps
+
+**To complete**
+
+## Updating
+
+**To complete**

ps-rule.yaml

@@ -0,0 +1,17 @@
+#
+# PSRule for Azure configuration
+#
+
+# Please see the documentation for all configuration options:
+# https://aka.ms/ps-rule/options
+# https://aka.ms/ps-rule-azure/options
+
+output:
+  culture:
+  - 'en-US'
+
+input:
+  pathIgnore:
+  - '.vscode/'
+  - '.github/'
+  - '*.md'