Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure package docs workflow #2348

Open
wants to merge 3 commits into
base: devel
Choose a base branch
from
+278 −196
Open

Restructure package docs workflow #2348

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f4f6b8f
fixes #2047 restructure package docs workflow
oraNod Jan 14, 2025
42e0b72
fix actionlint warning about input default
oraNod Jan 14, 2025
84876d0
update schedule to run twice a week
oraNod Jan 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
222 changes: 26 additions & 196 deletions .github/workflows/build-package-docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 on Tuesday and Thursday
- cron: '17 5 * * 2,4'
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:
Expand All @@ -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/[email protected]

- 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 }}
120 changes: 120 additions & 0 deletions .github/workflows/reusable-build-docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/[email protected]

- 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 }}"}'
Loading
Loading