Doc updates for V1.0.0 (#15)

* doc updates * more docs * add examples 1 and 2 * existing sub docs and changes * Auto-update Bicep Module Docs for PR 15 [jtracey93/f48dff4e] * Empty-Commit * update sidebar * add bicep version requirement * fix link * final docs for v1.0.0 * add linting suppression Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Azure · Oct 30, 2022 · 8cc78ac · 8cc78ac
1 parent f48dff4
commit 8cc78ac
Show file tree

Hide file tree

Showing 23 changed files with 1,042 additions and 382 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -20,7 +20,7 @@ Replace this with any testing evidence to show that your Pull Request works/fixe
 
 ## As part of this Pull Request I have
 
-- [ ] Read the [Contribution Guide](https://github.com/Azure/bicep-lz-vending/wiki/Contributing) and ensured this PR is compliant with the guide
+- [ ] Read the [Contribution Guide](https://github.com/Azure/bicep-lz-vending/wiki/contributing) and ensured this PR is compliant with the guide
 - [ ] Checked for duplicate [Pull Requests](https://github.com/Azure/bicep-lz-vending/pulls)
 - [ ] Associated it with relevant [GitHub Issues](https://github.com/Azure/bicep-lz-vending/issues)
 - [ ] *(ALZ Bicep Core Team Only)* Associated it with relevant [ADO Items](https://aka.ms/alz/bicep/backlog)

diff --git a/.github/scripts/Invoke-GitHubReleaseFetcher.ps1 b/.github/scripts/Invoke-GitHubReleaseFetcher.ps1
@@ -0,0 +1,204 @@
+####################################
+# Invoke-GitHubReleaseFetcher.ps1 #
+####################################
+# Version: 1.2.0
+# Last Modified: 26/10/2022
+# Author: Jack Tracey
+# Source: https://github.com/jtracey93/PublicScripts/blob/master/GitHub/PowerShell/Invoke-GitHubReleaseFetcher.ps1
+
+<#
+.SYNOPSIS
+Checks for the releases of a GitHub repository and downloads the latest release or all releases and pulls it into a specified directory, one for each version.
+.DESCRIPTION
+Checks for the releases of a GitHub repository and downloads the latest release or all releases and pulls it into a specified directory, one for each version.
+
+.EXAMPLE
+# Sync only latest release to PWD and keep only "version.json" file and "infra-as-code" directory (recursively)
+$keepThese = @("version.json", "infra-as-code")
+./Invoke-GitHubReleaseFetcher.ps1 -githubRepoUrl "https://github.com/Azure/ALZ-Bicep" -directoryAndFilesToKeep $keepThese
+
+# Sync only all releases to PWD and keep only "version.json" file and "infra-as-code" directory (recursively)
+$keepThese = @("version.json", "infra-as-code")
+./Invoke-GitHubReleaseFetcher.ps1 -githubRepoUrl "https://github.com/Azure/ALZ-Bicep" -syncAllReleases:$true -directoryAndFilesToKeep $keepThese
+
+.NOTES
+# Release notes 25/10/2021 - V1.0.0:
+- Initial release.
+
+# Release notes 26/10/2021 - V1.1.0:
+- Add support to move all extracted contents to release directories if $directoryAndFilesToKeep is not specified or is a empty array (which is the default).
+
+# Release notes 30/10/2021 - V1.2.0:
+- Add missing if condition to stop all files being added regardless of what is passed into `directoryAndFilesToKeep`.
+#>
+
+# Check for pre-reqs
+#Requires -PSEdition Core
+
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Required for colour outputs")]
+
+[CmdletBinding()]
+param (
+  #Added this back into parameters as error occurs if multiple tenants are found when using Get-AzTenant
+  [Parameter(Mandatory = $true, Position = 1, HelpMessage = "Please the provide the full URL of the GitHub repository you wish to check for the latest release.")]
+  [string]
+  $githubRepoUrl,
+
+  [Parameter(Mandatory = $false, Position = 2, HelpMessage = "Sync all releases from the specified GitHub repository. Defaults to false.")]
+  [bool]
+  $syncAllReleases = $false,
+
+  [Parameter(Mandatory = $false, Position = 3, HelpMessage = "The directory to download the releases to. Defaults to the current directory.")]
+  [string]
+  $directoryForReleases = "$PWD/releases",
+
+  [Parameter(Mandatory = $false, Position = 4, HelpMessage = "An array of strings contianing the paths to the directories or files that you wish to keep when downloading and extracting from the releases.")]
+  [array]
+  $directoryAndFilesToKeep = @()
+)
+
+# Start timer
+$StopWatch = New-Object -TypeName System.Diagnostics.Stopwatch
+$StopWatch.Start()
+
+# Split Repo URL into parts
+$repoOrgPlusRepo = $githubRepoUrl.Split("/")[-2..-1] -join "/"
+
+# Get releases on repo
+$repoReleasesUrl = "https://api.github.com/repos/$repoOrgPlusRepo/releases"
+$allRepoReleases = Invoke-RestMethod $repoReleasesUrl
+
+Write-Host ""
+Write-Host "=====> Checking for releases on GitHub Repo: $repoOrgPlusRepo" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "=====> All available releases on GitHub Repo: $repoOrgPlusRepo" -ForegroundColor Cyan
+$allRepoReleases | Select-Object name, tag_name, published_at, prerelease, draft, html_url | Format-Table -AutoSize
+
+# Get latest release on repo
+$latestRepoRelease = $allRepoReleases | Where-Object { $_.prerelease -eq $false } | Where-Object { $_.draft -eq $false } | Sort-Object -Descending published_at | Select-Object -First 1
+
+Write-Host ""
+Write-Host "=====> Latest available release on GitHub Repo: $repoOrgPlusRepo" -ForegroundColor Cyan
+$latestRepoRelease | Select-Object name, tag_name, published_at, prerelease, draft, html_url | Format-Table -AutoSize
+
+# Check if directory exists
+Write-Host ""
+Write-Host "=====> Checking if directory for releases exists: $directoryForReleases" -ForegroundColor Cyan
+
+if (!(Test-Path $directoryForReleases)) {
+  Write-Host ""
+  Write-Host "Directory does not exist for releases, will now create: $directoryForReleases" -ForegroundColor Yellow
+  New-Item -ItemType Directory -Path $directoryForReleases
+}
+
+# Pull all releases into directories
+if ($syncAllReleases -eq $true) {
+  Write-Host ""
+  Write-Host "=====> Syncing all releases of $repoOrgPlusRepo into $directoryForReleases" -ForegroundColor Cyan
+
+  foreach ($release in $allRepoReleases) {
+    $releaseDirectory = "$directoryForReleases/$($release.tag_name)"
+
+    Write-Host ""
+    Write-Host "===> Checking if directory for release version exists: $releaseDirectory" -ForegroundColor Cyan
+
+    if (!(Test-Path $releaseDirectory)) {
+      Write-Host ""
+      Write-Host "Directory does not exist for release $($release.tag_name), will now create: $releaseDirectory" -ForegroundColor Yellow
+      New-Item -ItemType Directory -Path $releaseDirectory
+    }
+
+    Write-Host ""
+    Write-Host "===> Checking if any content exists inside of $releaseDirectory" -ForegroundColor Cyan
+
+    $contentInReleaseDirectory = Get-ChildItem -Path $releaseDirectory -Recurse -ErrorAction SilentlyContinue
+
+    if ($null -eq $contentInReleaseDirectory) {
+      Write-Host ""
+      Write-Host "===> Pulling and extracting release $($release.tag_name) into $releaseDirectory" -ForegroundColor Cyan
+      New-Item -ItemType Directory -Path "$releaseDirectory/tmp"
+      Invoke-WebRequest -Uri "https://github.com/$repoOrgPlusRepo/archive/refs/tags/$($release.tag_name).zip" -OutFile "$releaseDirectory/tmp/$($release.tag_name).zip"
+      Expand-Archive -Path "$releaseDirectory/tmp/$($release.tag_name).zip" -DestinationPath "$releaseDirectory/tmp/extracted"
+      $extractedSubFolder = Get-ChildItem -Path "$releaseDirectory/tmp/extracted" -Directory
+
+      if ($null -ne $directoryAndFilesToKeep) {
+        foreach ($path in $directoryAndFilesToKeep) {
+          Write-Host ""
+          Write-Host "===> Moving $path into $releaseDirectory." -ForegroundColor Cyan
+          Move-Item -Path "$($extractedSubFolder.FullName)/$($path)" -Destination "$releaseDirectory" -ErrorAction SilentlyContinue
+        }
+      }
+
+      if ($null -eq $directoryAndFilesToKeep) {
+        Write-Host ""
+        Write-Host "===> Moving all extracted contents into $releaseDirectory." -ForegroundColor Cyan
+        Move-Item -Path "$($extractedSubFolder.FullName)/*" -Destination "$releaseDirectory" -ErrorAction SilentlyContinue
+      }
+
+      Remove-Item -Path "$releaseDirectory/tmp" -Force -Recurse
+
+    }
+    else {
+      Write-Host ""
+      Write-Host "===> Content already exists in $releaseDirectory. Skipping" -ForegroundColor Yellow
+    }
+  }
+}
+
+if ($syncAllReleases -eq $false) {
+  Write-Host ""
+  Write-Host "=====> Syncing latest release $($latestRepoRelease.tag_name) only of $repoOrgPlusRepo into $directoryForReleases" -ForegroundColor Cyan
+
+  $releaseDirectory = "$directoryForReleases/$($latestRepoRelease.tag_name)"
+
+  Write-Host ""
+  Write-Host "===> Checking if directory for release version exists: $releaseDirectory" -ForegroundColor Cyan
+
+  if (!(Test-Path $releaseDirectory)) {
+    Write-Host ""
+    Write-Host "Directory does not exist for release $($latestRepoRelease.tag_name), will now create: $releaseDirectory" -ForegroundColor Yellow
+    New-Item -ItemType Directory -Path $releaseDirectory
+  }
+
+  Write-Host ""
+  Write-Host "===> Checking if any content exists inside of $releaseDirectory" -ForegroundColor Cyan
+
+  $contentInReleaseDirectory = Get-ChildItem -Path $releaseDirectory -Recurse -ErrorAction SilentlyContinue
+
+  if ($null -eq $contentInReleaseDirectory) {
+    Write-Host ""
+    Write-Host "===> Pulling and extracting release $($latestRepoRelease.tag_name) into $releaseDirectory" -ForegroundColor Cyan
+    New-Item -ItemType Directory -Path "$releaseDirectory/tmp"
+    Invoke-WebRequest -Uri "https://github.com/$repoOrgPlusRepo/archive/refs/tags/$($latestRepoRelease.tag_name).zip" -OutFile "$releaseDirectory/tmp/$($latestRepoRelease.tag_name).zip"
+    Expand-Archive -Path "$releaseDirectory/tmp/$($latestRepoRelease.tag_name).zip" -DestinationPath "$releaseDirectory/tmp/extracted"
+    $extractedSubFolder = Get-ChildItem -Path "$releaseDirectory/tmp/extracted" -Directory
+
+    if ($null -ne $directoryAndFilesToKeep) {
+      foreach ($path in $directoryAndFilesToKeep) {
+        Write-Host ""
+        Write-Host "===> Moving $path into $releaseDirectory." -ForegroundColor Cyan
+        Move-Item -Path "$($extractedSubFolder.FullName)/$($path)" -Destination "$releaseDirectory" -ErrorAction SilentlyContinue
+      }
+    }
+
+    if ($null -eq $directoryAndFilesToKeep) {
+      Write-Host ""
+      Write-Host "===> Moving all extracted contents into $releaseDirectory." -ForegroundColor Cyan
+      Move-Item -Path "$($extractedSubFolder.FullName)/*" -Destination "$releaseDirectory" -ErrorAction SilentlyContinue
+    }
+
+    Remove-Item -Path "$releaseDirectory/tmp" -Force -Recurse
+
+  }
+  else {
+    Write-Host ""
+    Write-Host "===> Content already exists in $releaseDirectory. Skipping" -ForegroundColor Yellow
+  }
+}
+
+# Stop timer
+$StopWatch.Stop()
+
+# Display timer output as table
+Write-Host "Time taken to complete task:" -ForegroundColor Yellow
+$StopWatch.Elapsed | Format-Table
diff --git a/.github/workflows/gh-release-checker.yml b/.github/workflows/gh-release-checker.yml
@@ -0,0 +1,97 @@
+---
+name: Check & Pull Latest Upstream GitHub Release
+
+on:
+  schedule:
+    - cron: "0 0 * * 1-5"
+  workflow_dispatch: {}
+
+env:
+  remote_repository: "Azure/bicep-lz-vending"
+  branch_name: "pull-latest-upstream-release"
+  pr_title: "New Upstream GitHub Release Available"
+  pr_body: "This is an automated 'pull_request' containing the latest release from the upstream repo.\nPlease review the 'files changed' tab to review changes."
+
+jobs:
+  get-latest-release:
+    name: Check & Pull Latest Upstream GitHub Release
+    if: ${{ github.repository != 'Azure/bicep-lz-vending' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Local repository checkout
+        uses: actions/checkout@v3
+        with:
+          path: ${{ github.repository }}
+          fetch-depth: 0
+
+      - name: Configure local git
+        run: |
+          git config user.name github-actions
+          git config user.email [email protected]
+        working-directory: ${{ github.repository }}
+
+      - name: Create and checkout branch
+        run: |
+          BRANCH_URL="repos/${{ github.repository }}/branches"
+          JQ_FILTER=".[] | select(.name == \"${{ env.branch_name }}\").name"
+          CHECK_BRANCH_ORIGIN=$(gh api $BRANCH_URL | jq -r "$JQ_FILTER")
+          if [ -z "$CHECK_BRANCH_ORIGIN" ]
+          then
+            echo "Checkout local branch (create new, no origin)..."
+            git checkout -b ${{ env.branch_name }}
+          else
+            echo "Checkout local branch (create new, track from origin)..."
+            git checkout -b ${{ env.branch_name }} --track origin/${{ env.branch_name }}
+          fi
+        working-directory: ${{ github.repository }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.github_token }}
+
+      - name: Check for upstream release and pull if available
+        shell: pwsh
+        run: |
+          $keepThese = @("version.json", "src", "main.bicep", "main.bicep.parameters.md", "README.md")
+          .github/scripts/Invoke-GitHubReleaseFetcher.ps1 -githubRepoUrl "https://github.com/${{ env.remote_repository }}" -directoryAndFilesToKeep $keepThese -syncAllReleases:$false
+        working-directory: ${{ github.repository }}
+
+      - name: Check for changes
+        id: git_status
+        run: |
+          CHECK_GIT_STATUS=($(git status -s))
+          git status -s
+          echo "changes=${#CHECK_GIT_STATUS[@]}" >> $GITHUB_OUTPUT
+        working-directory: ${{ github.repository }}
+
+      - name: Add files, commit and push
+        if: steps.git_status.outputs.changes > 0
+        run: |
+          echo "Pushing changes to origin..."
+          git add releases
+          git add releases/*
+          git config --global core.autocrlf input
+          git commit -m '${{ env.pr_title }}'
+          git push origin ${{ env.branch_name }}
+        working-directory: ${{ github.repository }}
+
+      - name: Create pull request
+        if: steps.git_status.outputs.changes > 0
+        run: |
+          HEAD_LABEL="${{ github.repository_owner }}:${{ env.branch_name }}"
+          BASE_LABEL="${{ github.repository_owner }}:$(echo '${{ github.ref }}' | sed 's:refs/heads/::')"
+          PULL_REQUEST_URL="repos/${{ github.repository }}/pulls"
+          JQ_FILTER=".[] | select(.head.label == \"$HEAD_LABEL\") | select(.base.label == \"$BASE_LABEL\") | .url"
+          CHECK_PULL_REQUEST_URL=$(gh api $PULL_REQUEST_URL | jq -r "$JQ_FILTER")
+          if [ -z "$CHECK_PULL_REQUEST_URL" ]
+          then
+            CHECK_PULL_REQUEST_URL=$(gh pr create \
+            --title "${{ env.pr_title }}" \
+            --body "${{ env.pr_body }}" \
+            --base "${{ github.ref }}" \
+            --head "${{ env.branch_name }}")
+            echo "Created new PR: $CHECK_PULL_REQUEST_URL"
+          else
+            echo "Existing PR found: $CHECK_PULL_REQUEST_URL"
+          fi
+        working-directory: ${{ github.repository }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.github_token }}
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,9 @@
+{
+	// Recommended extensions for Bicep LZ Vending
+	"recommendations": [
+		"ms-azuretools.vscode-bicep",
+		"msazurermtools.azurerm-vscode-tools",
+		"bencoleman.armview",
+		"editorconfig.editorconfig"
+	]
+}