From f4f6b8f1f7abe81018ca522be35ed5d2bd05c328 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 14 Jan 2025 16:28:34 +0000 Subject: [PATCH 1/3] fixes #2047 restructure package docs workflow This change splits the package docs workflow into reusable parts for flexibility so that we can run different builds on various schedules. --- .github/workflows/build-package-docs.yaml | 222 +++----------------- .github/workflows/reusable-build-docs.yaml | 120 +++++++++++ .github/workflows/reusable-deploy-docs.yaml | 132 ++++++++++++ 3 files changed, 278 insertions(+), 196 deletions(-) create mode 100644 .github/workflows/reusable-build-docs.yaml create mode 100644 .github/workflows/reusable-deploy-docs.yaml diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 0ed27093500..04704ad061b 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -1,26 +1,30 @@ --- -name: Ansible package docs build +name: Build and deploy Ansible package docs on: schedule: - - cron: '17 5 * * *' # Run at 05:17 am + # Run at 05:17 am + - cron: '17 5 * * *' workflow_dispatch: inputs: repository-owner: description: GitHub account or org that owns the repository + type: string required: true default: ansible repository-name: description: Name of the GitHub repository + type: string required: true default: ansible-documentation repository-branch: description: Branch, tag, or commit SHA + type: string required: true default: devel ansible-package-version: - type: choice description: Ansible community package version + type: choice required: true default: devel options: @@ -29,211 +33,37 @@ on: - '10' - '9' deploy: - type: boolean description: Deploy the build + type: boolean required: true deployment-environment: - type: choice description: Deployment environment + type: choice required: true default: test options: - production - test -env: - PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version || 'devel' }} - jobs: build-package-docs: - runs-on: ubuntu-latest - steps: - - name: Checkout Ansible documentation - uses: actions/checkout@v4 - with: - repository: >- - ${{ - github.event.inputs.repository-owner || 'ansible' - }}/${{ - github.event.inputs.repository-name || 'ansible-documentation' - }} - ref: ${{ github.event.inputs.repository-branch || 'devel' }} - path: build-directory - - - name: Setup nox - uses: wntrblm/nox@2024.10.09 - - - name: Output Python info - run: python --version --version && which python - - - name: Graft ansible-core - run: nox -s clone-core - working-directory: build-directory - - - name: Install project requirements - run: >- - python -m pip install - -r tests/requirements.in - -c tests/requirements.txt - working-directory: build-directory - - - name: Set the COLLECTION_LIST variable - if: env.PACKAGE_VERSION != 'devel' - run: >- - echo COLLECTION_LIST="${PACKAGE_VERSION}" - >> "${GITHUB_ENV}" - - - name: Set the VERSION variable - run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" - - - name: Build the Ansible community package docs - run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" - working-directory: build-directory/docs/docsite - - - name: Create a tarball with the build contents - run: >- - tar -czvf - ansible-package-docs-html-"${PACKAGE_VERSION}"-"$(date '+%Y-%m-%d')"-${{ - github.run_id - }}-${{ - github.run_number - }}-${{ - github.run_attempt - }}.tar.gz - --directory=_build/html/ . - working-directory: build-directory/docs/docsite - - - name: Create a downloadable archive that contains the tarball - uses: actions/upload-artifact@v4 - with: - name: package-docs-build - path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz - retention-days: 7 + uses: ./.github/workflows/reusable-build-docs.yaml + with: + repository-owner: ${{ github.event.inputs.repository-owner }} + repository-name: ${{ github.event.inputs.repository-name }} + repository-branch: ${{ github.event.inputs.repository-branch }} + ansible-package-version: ${{ github.event.inputs.ansible-package-version }} + secrets: + DOCS_BOT_TOKEN: ${{ secrets.DOCS_BOT_TOKEN }} - check-deploy: + deploy-package-docs: if: github.event_name == 'workflow_dispatch' && github.event.inputs.deploy == 'true' needs: build-package-docs - runs-on: ubuntu-latest - steps: - - name: Log the workflow inputs if deployed - run: | - { - echo "## Deployment details :shipit:"; - echo "Publish to: ${{ github.event.inputs.deployment-environment }}"; - echo "Package version: ${{ github.event.inputs.ansible-package-version }}"; - echo "Owner: ${{ github.event.inputs.repository-owner }}"; - echo "Branch: ${{ github.event.inputs.repository-branch }}"; - } >> "${GITHUB_STEP_SUMMARY}" - - notify-build-failures: - if: failure() - needs: build-package-docs - runs-on: ubuntu-latest - env: - ROOM_URL: https://ansible-accounts.ems.host/_matrix/client/v3/rooms/!HJtetIFWYEIDBOXxFE:libera.chat/send/m.room.message - FAIL_MESSAGE: >- - Oh no! A community package docs build has failed. - Check this workflow run to see what went wrong: - https://github.com/ansible/ansible-documentation/actions/runs/${{ github.run_id }} - @orandon @samccann - steps: - - name: Set a transaction ID - run: echo "TX_ID=$(date +%s)" >> "${GITHUB_ENV}" - - - name: Notify the DaWGs in Matrix - run: | - curl -X PUT "${{ env.ROOM_URL }}/${TX_ID}" \ - -H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \ - -H "Content-Type: application/json" \ - -d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}' - - deploy-package-docs: - needs: - - check-deploy - runs-on: ubuntu-latest - environment: - name: deploy-package-docs - url: ${{ env.ENV_URL }} - env: - TARGET: ${{ github.event.inputs.deployment-environment }} - DEST_REPO: ansible-community/package-doc-builds - USER_EMAIL: "41898282+github-actions[bot]@users.noreply.github.com" - USER_NAME: "github-actions[bot]" - steps: - - name: Download the build archive - uses: actions/download-artifact@v4 - with: - name: package-docs-build - - - name: Extract the tarball - run: >- - tar -xvzf - ansible-package-docs-html-*.tar.gz - --one-top-level - - - name: Set the production branch and url - if: env.TARGET == 'production' - env: - BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }} - PROD_URL: https://ansible.readthedocs.io/projects/ansible - run: | - echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}" - echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}" - - - name: Set the test branch and url - if: env.TARGET == 'test' - env: - TEST_URL: https://ansible-community.github.io/package-doc-builds - run: | - echo "BRANCH=gh-pages" >> "${GITHUB_ENV}" - echo "ENV_URL=${TEST_URL}" >> "${GITHUB_ENV}" - - - name: Checkout the deploy directory - uses: actions/checkout@v4 - with: - repository: ${{ env.DEST_REPO }} - ref: ${{ env.BRANCH }} - path: deploy-directory - fetch-depth: 0 - ssh-key: ${{ secrets.DEPLOY_DOC_BUILD }} - persist-credentials: true - - - name: Copy the generated HTML and assets for production - run: >- - rsync -av --delete --mkpath - ansible-package-docs-html-*/ - deploy-directory/docs - - - name: Create a norobots.txt file for the test site - if: env.TARGET == 'test' - run: | - touch norobots.txt - echo "User-agent: *" > norobots.txt - echo "Disallow: /" >> norobots.txt - working-directory: deploy-directory/docs - - - name: Configure the git user - run: | - git config --local user.email "${USER_EMAIL}" - git config --local user.name "${USER_NAME}" - working-directory: deploy-directory - - - name: Git add the generated HTML and assets - run: git add ./docs --all --force - working-directory: deploy-directory - - - name: Commit generated HTML and assets - run: >- - git diff-index --quiet HEAD || - git commit -m "Push docs build $(date '+%Y-%m-%d')-${{ - github.run_id - }}-${{ - github.run_number - }}-${{ - github.run_attempt - }}" - working-directory: deploy-directory - - - name: Push build to deploy repository - run: git push origin - working-directory: deploy-directory + uses: ./.github/workflows/reusable-deploy-docs.yaml + with: + ansible-package-version: ${{ github.event.inputs.ansible-package-version }} + deployment-environment: ${{ github.event.inputs.deployment-environment }} + repository-owner: ${{ github.event.inputs.repository-owner }} + repository-branch: ${{ github.event.inputs.repository-branch }} + secrets: + DEPLOY_DOC_BUILD: ${{ secrets.DEPLOY_DOC_BUILD }} diff --git a/.github/workflows/reusable-build-docs.yaml b/.github/workflows/reusable-build-docs.yaml new file mode 100644 index 00000000000..ebfcc91c4f7 --- /dev/null +++ b/.github/workflows/reusable-build-docs.yaml @@ -0,0 +1,120 @@ +--- +name: Build Ansible package docs + +"on": + workflow_call: + inputs: + repository-owner: + description: GitHub account or org that owns the repository + type: string + required: false + default: ansible + repository-name: + description: Name of the GitHub repository + type: string + required: false + default: ansible-documentation + repository-branch: + description: Branch, tag, or commit SHA + type: string + required: false + default: devel + ansible-package-version: + type: string + description: Ansible community package version + required: false + default: devel + secrets: + DOCS_BOT_TOKEN: + required: true + +env: + PACKAGE_VERSION: ${{ inputs.ansible-package-version }} + +jobs: + build-package-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout Ansible documentation + uses: actions/checkout@v4 + with: + repository: >- + ${{ + inputs.repository-owner + }}/${{ + inputs.repository-name + }} + ref: ${{ inputs.repository-branch }} + path: build-directory + + - name: Setup nox + uses: wntrblm/nox@2024.10.09 + + - name: Output Python info + run: python --version --version && which python + + - name: Graft ansible-core + run: nox -s clone-core + working-directory: build-directory + + - name: Install project requirements + run: >- + python -m pip install + -r tests/requirements.in + -c tests/requirements.txt + working-directory: build-directory + + - name: Set the COLLECTION_LIST variable + if: env.PACKAGE_VERSION != 'devel' + run: >- + echo COLLECTION_LIST="${PACKAGE_VERSION}" + >> "${GITHUB_ENV}" + + - name: Set the VERSION variable + run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" + + - name: Build the Ansible community package docs + run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" + working-directory: build-directory/docs/docsite + + - name: Create a tarball with the build contents + run: >- + tar -czvf + ansible-package-docs-html-"${PACKAGE_VERSION}"-"$(date '+%Y-%m-%d')"-${{ + github.run_id + }}-${{ + github.run_number + }}-${{ + github.run_attempt + }}.tar.gz + --directory=_build/html/ . + working-directory: build-directory/docs/docsite + + - name: Create a downloadable archive that contains the tarball + uses: actions/upload-artifact@v4 + with: + name: package-docs-build + path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz + retention-days: 7 + + notify-build-failures: + if: failure() + needs: build-package-docs + runs-on: ubuntu-latest + env: + ROOM_URL: https://ansible-accounts.ems.host/_matrix/client/v3/rooms/!HJtetIFWYEIDBOXxFE:libera.chat/send/m.room.message + FAIL_MESSAGE: >- + Oh no! A community package docs build has failed. + Check this workflow run to see what went wrong: + https://github.com/ansible/ansible-documentation/actions/runs/${{ github.run_id }} + @orandon @samccann + steps: + - name: Set a transaction ID + run: echo "TX_ID=$(date +%s)" >> "${GITHUB_ENV}" + + - name: Notify the DaWGs in Matrix + run: | + curl -X PUT "${{ env.ROOM_URL }}/${TX_ID}" \ + -H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \ + -H "Content-Type: application/json" \ + -d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}' diff --git a/.github/workflows/reusable-deploy-docs.yaml b/.github/workflows/reusable-deploy-docs.yaml new file mode 100644 index 00000000000..1240ad9df3d --- /dev/null +++ b/.github/workflows/reusable-deploy-docs.yaml @@ -0,0 +1,132 @@ +--- +name: Deploy Ansible package docs + +"on": + workflow_call: + inputs: + repository-owner: + description: GitHub account or org that owns the repository + type: string + required: false + default: ansible + repository-branch: + description: Branch, tag, or commit SHA + type: string + required: false + default: devel + ansible-package-version: + type: string + description: Ansible community package version + required: false + default: devel + deployment-environment: + description: Deployment environment + type: string + required: true + default: test + secrets: + DEPLOY_DOC_BUILD: + required: true + +jobs: + log-inputs: + runs-on: ubuntu-latest + steps: + - name: Log the workflow inputs if deployed + run: | + { + echo "## Deployment details :shipit:"; + echo "Publish to: ${{ inputs.deployment-environment }}"; + echo "Package version: ${{ inputs.ansible-package-version }}"; + echo "Owner: ${{ inputs.repository-owner }}"; + echo "Branch: ${{ inputs.repository-branch }}"; + } >> "${GITHUB_STEP_SUMMARY}" + + deploy-package-docs: + runs-on: ubuntu-latest + environment: + name: deploy-package-docs + url: ${{ env.ENV_URL }} + env: + TARGET: ${{ github.event.inputs.deployment-environment }} + DEST_REPO: ansible-community/package-doc-builds + USER_EMAIL: "41898282+github-actions[bot]@users.noreply.github.com" + USER_NAME: "github-actions[bot]" + steps: + - name: Download the build archive + uses: actions/download-artifact@v4 + with: + name: package-docs-build + + - name: Extract the tarball + run: >- + tar -xvzf + ansible-package-docs-html-*.tar.gz + --one-top-level + + - name: Set the production branch and url + if: env.TARGET == 'production' + env: + BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }} + PROD_URL: https://ansible.readthedocs.io/projects/ansible + run: | + echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}" + echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}" + + - name: Set the test branch and url + if: env.TARGET == 'test' + env: + TEST_URL: https://ansible-community.github.io/package-doc-builds + run: | + echo "BRANCH=gh-pages" >> "${GITHUB_ENV}" + echo "ENV_URL=${TEST_URL}" >> "${GITHUB_ENV}" + + - name: Checkout the deploy directory + uses: actions/checkout@v4 + with: + repository: ${{ env.DEST_REPO }} + ref: ${{ env.BRANCH }} + path: deploy-directory + fetch-depth: 0 + ssh-key: ${{ secrets.DEPLOY_DOC_BUILD }} + persist-credentials: true + + - name: Copy the generated HTML and assets for production + run: >- + rsync -av --delete --mkpath + ansible-package-docs-html-*/ + deploy-directory/docs + + - name: Create a norobots.txt file for the test site + if: env.TARGET == 'test' + run: | + touch norobots.txt + echo "User-agent: *" > norobots.txt + echo "Disallow: /" >> norobots.txt + working-directory: deploy-directory/docs + + - name: Configure the git user + run: | + git config --local user.email "${USER_EMAIL}" + git config --local user.name "${USER_NAME}" + working-directory: deploy-directory + + - name: Git add the generated HTML and assets + run: git add ./docs --all --force + working-directory: deploy-directory + + - name: Commit generated HTML and assets + run: >- + git diff-index --quiet HEAD || + git commit -m "Push docs build $(date '+%Y-%m-%d')-${{ + github.run_id + }}-${{ + github.run_number + }}-${{ + github.run_attempt + }}" + working-directory: deploy-directory + + - name: Push build to deploy repository + run: git push origin + working-directory: deploy-directory From 42e0b72a1014301433e3de7a97e9253e0ce55b87 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 14 Jan 2025 17:29:09 +0000 Subject: [PATCH 2/3] fix actionlint warning about input default --- .github/workflows/reusable-deploy-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/reusable-deploy-docs.yaml b/.github/workflows/reusable-deploy-docs.yaml index 1240ad9df3d..e03fe441772 100644 --- a/.github/workflows/reusable-deploy-docs.yaml +++ b/.github/workflows/reusable-deploy-docs.yaml @@ -22,7 +22,7 @@ name: Deploy Ansible package docs deployment-environment: description: Deployment environment type: string - required: true + required: false default: test secrets: DEPLOY_DOC_BUILD: From 84876d04d78b4e5af1f2bb88509e55cdd5404487 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 14 Jan 2025 17:45:27 +0000 Subject: [PATCH 3/3] update schedule to run twice a week --- .github/workflows/build-package-docs.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 04704ad061b..8f1597fbdab 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -3,8 +3,8 @@ name: Build and deploy Ansible package docs on: schedule: - # Run at 05:17 am - - cron: '17 5 * * *' + # Run at 05:17 on Tuesday and Thursday + - cron: '17 5 * * 2,4' workflow_dispatch: inputs: repository-owner: