From 81e66a522dbf67eabf82e32543aeb584b0e695bc Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Wed, 19 Apr 2023 11:24:44 -0400 Subject: [PATCH 1/3] Use the GHA base container for Lint (Docs) This way, we can take advantage of the software the comes pre-installed on the GHA `ubuntu-latest` container image. Otherwise, we need to find a way to portably install Chromium on the `gravitational/docs` container in order to run the Mermaid CLI. Currently, the docs engine exits with an error during the "Lint (Docs)" job when attempting to build mermaid diagrams due to not being able to locate Chromium. For this change to work, the "Lint (Docs)" job checks out `gravitational/docs`, removes the default git submodule configuration, then adds a git submodule for the current `gravitational/teleport` branch. From there, it can install dependencies via `yarn` and run our CI scripts. --- .github/workflows/doc-tests.yaml | 37 +++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/.github/workflows/doc-tests.yaml b/.github/workflows/doc-tests.yaml index 0eb4c97bc8666..f08474352ad22 100644 --- a/.github/workflows/doc-tests.yaml +++ b/.github/workflows/doc-tests.yaml @@ -19,30 +19,43 @@ jobs: permissions: contents: read - container: - image: ghcr.io/gravitational/docs:latest - volumes: - - ${{ github.workspace }}:/src/content/docs - steps: - name: Checkout uses: actions/checkout@v3 + with: + repository: "gravitational/docs" + path: "docs" - name: Prepare docs site configuration + # The environment we use for linting the docs differs from the one we + # use for the live docs site in that we only test a single version of + # the content. + # + # To do this, we replace the three submodules we use for building the + # live docs site with a single submodule, pointing to the + # gravitational/teleport branch we are linting. + # # The docs engine expects a config.json file at the root of the # gravitational/docs clone that associates directories with git - # submodules. - # - # By default, these directories represent versioned branches + # submodules. By default, these directories represent versioned branches # of gravitational/teleport. We override this in order to build only a # single version of the docs. - run: 'echo "{\"versions\": [{\"name\": \"docs\", \"branch\": \"$GITHUB_REF_NAME\", \"deprecated\": false}]}" > /src/config.json' + run: | + cd $GITHUB_WORKSPACE/docs + echo "" > .gitmodules + rm -rf content/* + cd content + git submodule add --force -b $GITHUB_HEAD_REF -- https://github.com/gravitational/teleport + cd $GITHUB_WORKSPACE/docs + echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$GITHUB_HEAD_REF\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json + yarn install + yarn build-node - name: Check spelling - run: cd /src && yarn spellcheck /src/content/docs + run: cd $GITHUB_WORKSPACE/docs && yarn spellcheck content/teleport - name: Lint the docs - run: cd /src && yarn markdown-lint + run: cd $GITHUB_WORKSPACE/docs && yarn markdown-lint - name: Test the docs build - run: cd /src && yarn install && yarn build + run: cd $GITHUB_WORKSPACE/docs && yarn install && yarn build From 151771c69836d98146cd452022dfe3cfc7eea27d Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Wed, 3 May 2023 17:09:27 -0400 Subject: [PATCH 2/3] s/GITHUB_HEAD_REF/GITHUB_SHA/ --- .github/workflows/doc-tests.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/doc-tests.yaml b/.github/workflows/doc-tests.yaml index f08474352ad22..9ceb4ca7b1654 100644 --- a/.github/workflows/doc-tests.yaml +++ b/.github/workflows/doc-tests.yaml @@ -45,9 +45,9 @@ jobs: echo "" > .gitmodules rm -rf content/* cd content - git submodule add --force -b $GITHUB_HEAD_REF -- https://github.com/gravitational/teleport + git submodule add --force -b $GITHUB_SHA -- https://github.com/gravitational/teleport cd $GITHUB_WORKSPACE/docs - echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$GITHUB_HEAD_REF\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json + echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$GITHUB_SHA\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json yarn install yarn build-node From 525565b4f53012061245d0f63d003fb267d53e52 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 4 May 2023 17:22:12 -0400 Subject: [PATCH 3/3] Base the submodule branch source on the event type --- .github/workflows/doc-tests.yaml | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/.github/workflows/doc-tests.yaml b/.github/workflows/doc-tests.yaml index 9ceb4ca7b1654..35517775248da 100644 --- a/.github/workflows/doc-tests.yaml +++ b/.github/workflows/doc-tests.yaml @@ -41,13 +41,26 @@ jobs: # of gravitational/teleport. We override this in order to build only a # single version of the docs. run: | + if [ $GITHUB_EVENT_NAME = "pull_request" ]; then + BRANCH=$GITHUB_HEAD_REF; + elif [ $GITHUB_EVENT_NAME = "merge_group" ]; then + # GitHub populates $GITHUB_REF with: + # refs/heads/gh-readonly-queue//pr-- + # + # We strip the "refs/heads/" prefix so we can check out the branch. + BRANCH=$(echo $GITHUB_REF | sed -E "s|refs/heads/(.*)|\1|") + else + echo "Unexpected event name: $GITHUB_EVENT_NAME"; + exit 1; + fi + cd $GITHUB_WORKSPACE/docs echo "" > .gitmodules rm -rf content/* cd content - git submodule add --force -b $GITHUB_SHA -- https://github.com/gravitational/teleport + git submodule add --force -b $BRANCH -- https://github.com/gravitational/teleport cd $GITHUB_WORKSPACE/docs - echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$GITHUB_SHA\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json + echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json yarn install yarn build-node