From 2e35f5300a698740752b54e5f7211c7da5225193 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jun 2022 12:13:25 +0100 Subject: [PATCH] Add publishing workflows for next (unreleased) and released documentation Notable features: - Merges are blocked by strict Hugo reference checking. However, this only works for references that resolve within the repository. Once you have Hugo references to website pages beyond this repository, you will want to remove this test job. - Pushes to main are automatically published to "next" documentation consistent with our other OSS projects. - Pushes of release tags publish to a versioned directory in the website. The website uses `v..x` versioning and the "Determine technical documentation version" step will make sure that a tag such as `v0.20.7` is mapped to `v0.20.x`. - Pushes to release branches will only be published if there is an existing corresponding release tag. For example, pushing to a new release branch `release-0.1000` will not trigger a publish of documentation until there is a `v0.1000.0` release tag. > **Note:** I have used a release branch naming convention `release--` which is consistent with grafana/mimir but I see that in the old amixr repository there are long lived release branches for patch versions. If that is required. I can update this PR to support that but I would recommend not including patch versions in release branch naming unless you have a good reason to do so. Signed-off-by: Jack Baldry --- .../publish-technical-documentation-next.yml | 42 +++++++++++ ...ublish-technical-documentation-release.yml | 74 +++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 .github/workflows/publish-technical-documentation-next.yml create mode 100644 .github/workflows/publish-technical-documentation-release.yml diff --git a/.github/workflows/publish-technical-documentation-next.yml b/.github/workflows/publish-technical-documentation-next.yml new file mode 100644 index 00000000..1e0e3e9c --- /dev/null +++ b/.github/workflows/publish-technical-documentation-next.yml @@ -0,0 +1,42 @@ +name: "publish-technical-documentation-next" + +on: + push: + branches: + - "main" + paths: + - "docs/sources/**" + workflow_dispatch: +jobs: + test: + runs-on: "ubuntu-latest" + steps: + - name: "Check out code" + uses: "actions/checkout@v3" + - name: "Build website" + # -e HUGO_REFLINKSERRORLEVEL=ERROR prevents merging broken refs with the downside + # that no refs to external content can be used as these refs will not resolve in the + # docs-base image. + run: | + docker run -v ${PWD}/docs/sources:/hugo/content/docs/oncall/latest -e HUGO_REFLINKSERRORLEVEL=ERROR --rm grafana/docs-base:latest /bin/bash -c 'make hugo' + + sync: + runs-on: "ubuntu-latest" + needs: "test" + steps: + - name: "Check out code" + uses: "actions/checkout@v3" + + - name: "Clone website-sync Action" + run: "git clone --single-branch --no-tags --depth 1 -b master https://grafanabot:${{ secrets.GH_BOT_ACCESS_TOKEN }}@github.com/grafana/website-sync ./.github/actions/website-sync" + + - name: "Publish to website repository (next)" + uses: "./.github/actions/website-sync" + id: "publish-next" + with: + repository: "grafana/website" + branch: "master" + host: "github.com" + github_pat: "${{ secrets.GH_BOT_ACCESS_TOKEN }}" + source_folder: "docs/sources" + target_folder: "content/docs/oncall/next" diff --git a/.github/workflows/publish-technical-documentation-release.yml b/.github/workflows/publish-technical-documentation-release.yml new file mode 100644 index 00000000..423bd497 --- /dev/null +++ b/.github/workflows/publish-technical-documentation-release.yml @@ -0,0 +1,74 @@ +name: "publish-technical-documentation-release" + +on: + push: + branches: + - "release-*" + tags: + - "v[0-9]+.[0-9]+.[0-9]+" + paths: + - "docs/sources/**" + workflow_dispatch: +jobs: + test: + runs-on: "ubuntu-latest" + steps: + - name: "Check out code" + uses: "actions/checkout@v3" + - name: + "Build website" + # -e HUGO_REFLINKSERRORLEVEL=ERROR prevents merging broken refs with the downside + # that no refs to external content can be used as these refs will not resolve in the + # docs-base image. + run: | + docker run -v ${PWD}/docs/sources:/hugo/content/docs/mimir/latest -e HUGO_REFLINKSERRORLEVEL=ERROR --rm grafana/docs-base:latest /bin/bash -c 'make hugo' + + sync: + runs-on: "ubuntu-latest" + needs: "test" + steps: + - name: "Checkout code and tags" + uses: "actions/checkout@v3" + with: + fetch-depth: 0 + + - name: "Checkout Actions library" + uses: "actions/checkout@v3" + with: + repository: "grafana/grafana-github-actions" + path: "./actions" + + - name: "Install Actions from library" + run: "npm install --production --prefix ./actions" + + - name: "Determine if there is a matching release tag" + id: "has-matching-release-tag" + uses: "./actions/has-matching-release-tag" + with: + ref_name: "${{ github.ref_name }}" + release_tag_regexp: "^v(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$" + release_branch_regexp: "^release-(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$" + + - name: "Determine technical documentation version" + if: "steps.has-matching-release-tag.outputs.bool == 'true'" + uses: "./actions/docs-target" + id: "target" + with: + ref_name: "${{ github.ref_name }}" + + - name: "Clone website-sync Action" + if: "steps.has-matching-release-tag.outputs.bool == 'true'" + run: "git clone --single-branch --no-tags --depth 1 -b master https://grafanabot:${{ secrets.GH_BOT_ACCESS_TOKEN }}@github.com/grafana/website-sync ./.github/actions/website-sync" + + - name: "Publish to website repository (release)" + if: "steps.has-matching-release-tag.outputs.bool == 'true'" + uses: "./.github/actions/website-sync" + id: "publish-release" + with: + repository: "grafana/website" + branch: "master" + host: "github.com" + github_pat: "${{ secrets.GH_BOT_ACCESS_TOKEN }}" + source_folder: "docs/sources" + # Append ".x" to target to produce a v..x directory. + target_folder: "content/docs/oncall/${{ steps.target.outputs.target }}.x"