From 3a934696f1857f797d775b3059cedeed2a5287a7 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 e631f0a7eeba5b2315fc4a99527b261eeea8654c 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 9e8669c51c26b9179ea2064db8763a185e96fcf0 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