Skip to content

Documentation - - refs/heads/main #290

Documentation - - refs/heads/main

Documentation - - refs/heads/main #290

name: Documentation
run-name: 'Documentation - ${{ inputs.oci-image-name }} - ${{ github.ref }}'
on:
push:
paths:
- "oci/*/documentation.y*ml"
branches:
- main
workflow_dispatch:
inputs:
oci-image-name:
description: 'OCI image to generate the documentation for'
required: true
external_ref_id: # (1)
description: 'Optional ID for unique run detection'
required: false
type: string
default: "default-id"
workflow_call:
inputs:
oci-image-name:
description: 'OCI image to generate the documentation for'
required: true
type: string
release-commit-sha:
description: 'Commit SHA containing the updated _releases.json'
required: true
type: string
jobs:
validate-documentation-request:
runs-on: ubuntu-22.04
name: Validate documentation request
outputs:
oci-img-path: ${{ steps.validate-image.outputs.img-path }}
oci-img-name: ${{ steps.validate-image.outputs.img-name }}
steps:
- name: ${{ inputs.external_ref_id }} # (2)
if: ${{ github.event_name == 'workflow_dispatch' }}
run: echo 'Started by ${{ inputs.external_ref_id }}' >> "$GITHUB_STEP_SUMMARY"
- uses: actions/checkout@v4
- name: Validate access to triggered image
uses: ./.github/actions/validate-actor
if: ${{ github.repository == 'canonical/oci-factory' }}
with:
admin-only: true
image-path: "oci/${{ inputs.oci-image-name }}"
github-token: ${{ secrets.ROCKSBOT_TOKEN }}
- name: Infer images to document
uses: tj-actions/changed-files@v35
id: changed-files
if: github.event_name != 'workflow_dispatch' && github.event_name != 'workflow_call'
with:
dir_names: "true"
separator: ","
files: |
oci/*/documentation.y*ml
- name: Validate image from dispatch
id: validate-image
run: |
set -ex
# check if this is coming from a workflow dispatch/call
# as checking github.event_name isn't reliable here
if [ "${{ inputs.oci-image-name }}" != "" ]
then
img_path="oci/${{ inputs.oci-image-name }}"
else
img_path="${{ steps.changed-files.outputs.all_changed_files }}"
occurrences="${img_path//[^,]}"
if [ ${#occurrences} -ne 0 ]
then
echo "ERR: can only build documentation for 1 image at a time, but trying to document ${img_path}"
exit 1
fi
fi
test -d "${img_path}"
echo "img-name=$(basename ${img_path})" >> "$GITHUB_OUTPUT"
echo "img-path=${img_path}" >> "$GITHUB_OUTPUT"
do-documentation:
runs-on: ubuntu-22.04
name: Documentation
needs: [validate-documentation-request]
env:
IS_PROD: ${{ ! startsWith(needs.validate-documentation-request.outputs.oci-img-name, 'mock-') }}
steps:
- uses: actions/checkout@v4
with:
ref: ${{ inputs.release-commit-sha }}
- uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Setup environment
run: pip install -r ./src/image/requirements.txt -r ./src/docs/requirements.txt
- name: Get all revisions per track
id: get-all-canonical-tags
env:
OS_USERNAME: ${{ secrets.SWIFT_OS_USERNAME }}
OS_TENANT_NAME: ${{ secrets.SWIFT_OS_TENANT_NAME }}
OS_PASSWORD: ${{ secrets.SWIFT_OS_PASSWORD }}
OS_REGION_NAME: ${{ secrets.SWIFT_OS_REGION_NAME }}
OS_STORAGE_URL: ${{ secrets.SWIFT_OS_STORAGE_URL }}
IMAGE_NAME: "${{ needs.validate-documentation-request.outputs.oci-img-name }}"
SWIFT_CONTAINER_NAME: ${{ vars.SWIFT_CONTAINER_NAME }}
run: |
./src/image/get_canonical_tags_from_swift.sh
- name: Generate documentation for ${{ needs.validate-documentation-request.outputs.oci-img-name }}
id: generate-documentation
env:
ECR_CREDS_USR: ${{ env.IS_PROD == 'true' && secrets.ECR_CREDS_USR || secrets.ECR_CREDS_USR_DEV }}
ECR_CREDS_PSW: ${{ env.IS_PROD == 'true' && secrets.ECR_CREDS_PSW || secrets.ECR_CREDS_PSW_DEV }}
ECR_NAMESPACE: ${{ env.IS_PROD == 'true' && 'ubuntu' || secrets.ECR_NAMESPACE_DEV }}
run: |
set -ex
python3 -m src.docs.generate_oci_doc_yaml \
--all-revision-tags "${{ steps.get-all-canonical-tags.outputs.canonical-tags-file }}" \
--ecr-api-key "${ECR_CREDS_USR}" \
--ecr-api-secret "${ECR_CREDS_PSW}" \
--oci-image-path "${{ needs.validate-documentation-request.outputs.oci-img-path }}" \
--repository "${ECR_NAMESPACE}" \
--doc-data-dir data
- name: Upload documentation data YAML
uses: actions/upload-artifact@v4
with:
name: '${{ needs.validate-documentation-request.outputs.oci-img-name }}.doc.yaml'
path: "${{ steps.generate-documentation.outputs.image_doc_folder }}/*.y*ml"
if-no-files-found: error
- name: Publish Documentation for ${{ needs.validate-documentation-request.outputs.oci-img-name }}
env:
# In Dev, images go into the personal space of DOCKER_HUB_CREDS_USR_DEV
# so we can reuse its username (with a more privileged PAT) for updating the docs.
# In Prod, however, since it's an org, the collaborating DH account is different to
# segregate access and ensure other jobs in this pipeline don't abuse the privileged
# access that is needed here, for updating the docs.
DOCKER_HUB_CREDS_PSW_DOC: ${{ env.IS_PROD == 'true' && secrets.DOCKER_HUB_CREDS_PSW_DOC || secrets.DOCKER_HUB_CREDS_PSW_DOC_DEV }}
DOCKER_HUB_CREDS_USR_DOC: ${{ env.IS_PROD == 'true' && secrets.DOCKER_HUB_CREDS_USR_DOC || secrets.DOCKER_HUB_CREDS_USR_DEV }}
ECR_CREDS_USR: ${{ env.IS_PROD == 'true' && secrets.ECR_CREDS_USR || secrets.ECR_CREDS_USR_DEV }}
ECR_CREDS_PSW: ${{ env.IS_PROD == 'true' && secrets.ECR_CREDS_PSW || secrets.ECR_CREDS_PSW_DEV }}
ECR_REGISTRY_ID: ${{ env.IS_PROD == 'true' && secrets.ECR_REGISTRY_ID || secrets.ECR_REGISTRY_ID_DEV }}
DOCKER_HUB_NAMESPACE: ${{ env.IS_PROD == 'true' && 'docker.io/ubuntu' || secrets.DOCKER_HUB_NAMESPACE_DEV }}
run: |
set -ex
./src/docs/publish_docs.sh "${{ needs.validate-documentation-request.outputs.oci-img-name }}" "${{ steps.generate-documentation.outputs.name_doc_file }}" "${{ steps.generate-documentation.outputs.image_doc_folder }}"
notify:
runs-on: ubuntu-22.04
name: Notify on failure
needs: [validate-documentation-request, do-documentation]
if: ${{ !cancelled() && contains(needs.*.result, 'failure') && github.event_name != 'workflow_dispatch' }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Summarize workflow failure message
id: get-summary
run: |
echo '${{ toJson(needs) }}' > jobs.json
./src/notifications/summarize_workflow_results.py --jobs-file jobs.json
- name: Get contacts for ${{ needs.validate-documentation-request.outputs.oci-img-name }}
id: get-contacts
working-directory: ${{ needs.validate-documentation-request.outputs.oci-img-path }}
run: |
mm_channels=$(yq -r '.notify | ."mattermost-channels" | join(",")' < contacts.y*ml)
echo "mattermost-channels=${mm_channels}" >> "$GITHUB_OUTPUT"
- name: Notify via Mattermost
env:
MM_BOT_TOKEN: ${{ secrets.MM_BOT_TOKEN }}
FINAL_STATUS: failure
MM_SERVER: ${{ secrets.MM_SERVER }}
URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
SUMMARY: ${{ steps.get-summary.outputs.summary }}
FOOTER: "Triggered by ${{ github.triggering_actor }}. Ref: ${{ github.ref }}. Attempts: ${{ github.run_attempt }}"
TITLE: '${{ needs.validate-documentation-request.outputs.oci-img-name }}: failed to generate docs'
run: |
for channel in $(echo ${{ steps.get-contacts.outputs.mattermost-channels }} | tr ',' ' ')
do
MM_CHANNEL_ID="${channel}" ./src/notifications/send_to_mattermost.sh
done