ci.yml

name: CI

on:
  push:
  schedule:
    # Run this around 2:37am once every 6-ish days to keep the GitHub API
    # cache warm. Otherwise we would run into an API rate limit whenever
    # we resume working on the repository after a weeks-long break.
    #
    # Github Actions caches are evicted after one week of not being used.
    - cron: '37 2 1,7,13,19,25,31 * *'

permissions:
  contents: read
  # implicitly all other scopes not listed become none

jobs:
  pdf_creation:
    strategy:
      matrix:
        element:
          - {name: Crypto Documentation, dir: docs/cryptodoc, out_name: cryptodoc}
          - {name: Audit Method Description, dir: docs/audit_method, out_name: audit_method}
          - {name: Test Specification, dir: docs/testspec, out_name: testspec}
          - {name: Architecture Overview, dir: docs/architecture, out_name: architecture}

    name: Build PDF - ${{ matrix.element.name }}
    runs-on: ubuntu-24.04
    defaults:
      run:
        working-directory: ${{matrix.element.dir }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Environment Configuration
        uses: ./.github/actions/setup-environment
        with:
          env_file: ./config/botan.env

      - name: Install Build Dependencies
        run: |
          sudo apt-get update
          sudo apt-get -qq install python3-poetry texlive-latex-extra texlive-fonts-recommended tex-gyre texlive-lang-german latexmk
      - name: Install Python Dependencies
        run: poetry install --no-dev
      - name: Build pdf
        run: poetry run make latexpdf

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.element.out_name }}
          path: ${{ matrix.element.dir }}/_build/latex/${{ matrix.element.out_name }}-*.pdf

  url_check:
    strategy:
      matrix:
        element:
          - {name: Crypto Documentation, dir: docs/cryptodoc}
          - {name: Audit Method Description, dir: docs/audit_method}
          - {name: Test Specification, dir: docs/testspec}
          - {name: Architecture, dir: docs/architecture}

    name: Check source URLs - ${{ matrix.element.name }}
    runs-on: ubuntu-24.04
    defaults:
      run:
        working-directory: ${{matrix.element.dir }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Environment Configuration
        uses: ./.github/actions/setup-environment
        with:
          env_file: ./config/botan.env

      - name: Install Build Dependencies
        run: |
          sudo apt-get update
          sudo apt-get -qq install python3-poetry
      - name: Install Python Dependencies
        run: poetry install --no-dev

      - name: Build with URL check enabled
        run: poetry run make SPHINXOPTS="-D src_ref_check_url=True -W --keep-going" html

  audit_generation:
    name: Build PDF - Audit Report
    runs-on: ubuntu-24.04
    steps:
      - name: Fetch Audit Repository
        uses: actions/checkout@v4
        with:
          path: ./source

      - name: Setup Environment Configuration
        uses: ./source/.github/actions/setup-environment
        with:
          env_file: ./source/config/botan.env

      - name: Fetch Botan Repository
        uses: actions/checkout@v4
        with:
          path: ./botan
          repository: ${{ env.BOTAN_REPO }}
          fetch-depth: 0

      - name: Install Build Dependencies
        working-directory: source/docs/audit_report
        run: |
          sudo apt-get update
          sudo apt-get -qq install python3-poetry texlive-latex-extra texlive-fonts-recommended tex-gyre latexmk
          poetry install --no-dev

      - name: Install GitHub webflow GPG public key
        run: gpg --trusted-key 4AEE18F83AFDEB23 --import source/.github/resources/web-flow.gpg

      - name: Handle the Audit Generator Cache
        uses: actions/cache@v4
        with:
          path: ./audit_generator_cache
          key: audit_3.1-${{ github.run_id }}
          restore-keys: audit_3.1
          save-always: true

      - name: Verify Patch Coverage
        working-directory: source/docs/audit_report
        run: poetry run python3 -m genaudit.cli unrefed --yaml changes
        env:
          AUDIT_CACHE_LOCATION: ${{ github.workspace }}/audit_generator_cache
          AUDIT_REPO_LOCATION: ${{ github.workspace }}/botan
          BASIC_GH_TOKEN: ${{ github.token }}

      - name: Check Patch Audit Status
        working-directory: source/docs/audit_report
        run: poetry run python3 -m genaudit.cli verify_audits changes
        env:
          AUDIT_CACHE_LOCATION: ${{ github.workspace }}/audit_generator_cache
          AUDIT_REPO_LOCATION: ${{ github.workspace }}/botan
          BASIC_GH_TOKEN: ${{ github.token }}

      - name: Build Document
        working-directory: source/docs/audit_report
        run: poetry run make latexpdf
        env:
          AUDIT_CACHE_LOCATION: ${{ github.workspace }}/audit_generator_cache
          AUDIT_REPO_LOCATION: ${{ github.workspace }}/botan
          BASIC_GH_TOKEN: ${{ github.token }}

      - name: Check Source Links
        working-directory: source/docs/audit_report
        run: poetry run make SPHINXOPTS="-D src_ref_check_url=True -W --keep-going" html
        env:
          AUDIT_CACHE_LOCATION: ${{ github.workspace }}/audit_generator_cache
          AUDIT_REPO_LOCATION: ${{ github.workspace }}/botan
          BASIC_GH_TOKEN: ${{ github.token }}

      - name: Query the API Rate Limit
        run: ${{ github.workspace }}/source/.github/scripts/query_rate_limit.sh
        if: always()
        env:
          GITHUB_TOKEN: ${{ github.token }}

      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: audit_report
          path: source/docs/audit_report/_build/latex/*.pdf

  utility:
    name: "Utility"
    strategy:
      fail-fast: false

      matrix:
        include:
          - jobname: Documentation
            target: pdf_docs
            artifact_name: documentation
            artifacts: |
              build/build/docs/handbook/botan.pdf
              build/build/docs/doxygen.zip
            host_os: ubuntu-latest
          - jobname: Coverage Report
            target: coverage
            artifact_name: coverage
            artifacts: build/coverage.zip
            host_os: ubuntu-latest

    runs-on: ${{ matrix.host_os }}
    steps:
      - name: Fetch Audit Repository
        uses: actions/checkout@v4
        with:
          path: ./source

      - name: Setup Environment Configuration
        uses: ./source/.github/actions/setup-environment
        with:
          env_file: ./source/config/botan.env

      - name: Fetch Botan Repository
        uses: actions/checkout@v4
        with:
          path: ./botan
          repository: ${{ env.BOTAN_REPO }}
          fetch-depth: 0
          ref: ${{ env.BOTAN_REF }}

      - name: Setup Build Agent
        uses: ./source/.github/actions/setup-build-agent
        with:
          target: ${{ matrix.target }}
          cache-key: bsi-${{ matrix.host_os }}-${{ matrix.target }}

      - name: Build and Test Botan
        run: >-
          python3 ./source/.github/scripts/ci_build.py
          --root-dir=${{ github.workspace }}/botan --build-dir=${{ github.workspace }}/build
          ${{ matrix.target }}

      - name: Archive Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.artifact_name }}
          path: ${{ matrix.artifacts }}
        if: ${{ matrix.artifacts != '' }}

  bsi_tests:
    name: "BSI Build Policy Tests"
    strategy:
      fail-fast: false

      matrix:
        # basic configuration combinations should run on all target platforms
        target:    [ static, shared ]
        platform:  [
          { host_os: windows-2022,  compiler: msvc,  make_tool: ninja },
          { host_os: ubuntu-latest, compiler: gcc,   make_tool: make },
          { host_os: ubuntu-latest, compiler: clang, make_tool: make },
          { host_os: macos-13,  compiler: xcode, make_tool: make }, # Intel
          { host_os: macos-14,  compiler: xcode, make_tool: make }  # Apple Silicon
        ]

    runs-on: ${{ matrix.platform.host_os }}

    steps:
      - name: Fetch Audit Repository
        uses: actions/checkout@v4
        with:
          path: ./source

      - name: Setup Environment Configuration
        uses: ./source/.github/actions/setup-environment
        with:
          env_file: ./source/config/botan.env

      - name: Fetch Botan Repository
        uses: actions/checkout@v4
        with:
          path: ./botan
          repository: ${{ env.BOTAN_REPO }}
          fetch-depth: 0
          ref: ${{ env.BOTAN_REF }}

      - name: Setup Build Agent
        uses: ./source/.github/actions/setup-build-agent
        with:
          target: ${{ matrix.target }}
          cache-key: bsi-${{ matrix.platform.host_os }}-${{ matrix.platform.compiler }}-${{ matrix.target }}

      - name: Build and Test Botan
        run: >-
          python3 ./source/.github/scripts/ci_build.py
          --root-dir=${{ github.workspace }}/botan --build-dir=${{ github.workspace }}/build
          --cc='${{ matrix.platform.compiler }}' --make-tool='${{ matrix.platform.make_tool }}'
          --test-results-dir=junit_reports
          ${{ matrix.target }}

      - name: Store JUnit Report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: junit-${{ matrix.platform.host_os }}-${{ matrix.platform.compiler }}-${{ matrix.target }}
          path: junit_reports/*.xml
          if-no-files-found: error

  test_report:
    name: "Generate Test Report"
    needs: bsi_tests
    if: always()
    runs-on: ubuntu-24.04
    defaults:
      run:
        working-directory: docs/testreport
    steps:
      - uses: actions/checkout@v4

      - name: Setup Environment Configuration
        uses: ./.github/actions/setup-environment
        with:
          env_file: ./config/botan.env

      - name: Fetch JUnit Reports
        uses: actions/download-artifact@v4
        with:
          pattern: junit-*
          merge-multiple: true
          path: ${{ github.workspace }}/junit_reports

      - name: Install Build Dependencies
        run: |
          sudo apt-get update
          sudo apt-get -qq install python3-poetry texlive-latex-extra texlive-fonts-recommended tex-gyre texlive-lang-german latexmk
      - name: Install Python Dependencies
        run: poetry install --no-dev
      - name: Build pdf
        run: poetry run make latexpdf
        env:
          TEST_REPORT_JUNIT_INPUT_DIRECTORY: ${{ github.workspace }}/junit_reports

      - name: Store Test Report
        uses: actions/upload-artifact@v4
        with:
          name: testreport
          path: docs/testreport/_build/latex/testreport-*.pdf
          if-no-files-found: error

  source_archive:
    name: "Source Archive"
    runs-on: ubuntu-latest
    steps:
      - name: Fetch Audit Repository
        uses: actions/checkout@v4
        with:
          path: ./source

      - name: Setup Environment Configuration
        uses: ./source/.github/actions/setup-environment
        with:
          env_file: ./source/config/botan.env

      - name: Fetch Botan Repository
        uses: actions/checkout@v4
        with:
          path: ./botan
          repository: ${{ env.BOTAN_REPO }}
          fetch-depth: 0
          ref: ${{ env.BOTAN_REF }}

      - name: Generate Archive
        run: python3 ${{ github.workspace }}/source/.github/scripts/tarball.py --output-dir build --source-dir botan

      - name: Archive Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: source
          path: build/*.zip

  check_upstream_source_archive:
    name: "Check Upstream Source Archive"
    runs-on: ubuntu-24.04
    steps:
      - name: Fetch Audit Repository
        uses: actions/checkout@v4
        with:
          path: ./source

      - name: Setup Environment Configuration
        uses: ./source/.github/actions/setup-environment
        with:
          env_file: ./source/config/botan.env

      - name: Detect when a Release Version is being built
        run: |
          if [[ "${BOTAN_VERSION}" == "${BOTAN_REF}" ]]; then
            echo "We seem to build a release version"
            echo "BUILDING_RELEASE=true" >> $GITHUB_ENV
          else
            echo "We seem to build a development version"
            echo "BUILDING_RELEASE=false" >> $GITHUB_ENV
          fi

      - name: Install Build Dependencies
        if: ${{ env.BUILDING_RELEASE == 'true' }}
        working-directory: source/tools/tarball_checker
        run: |
          sudo apt-get update
          sudo apt-get -qq install python3-poetry
          poetry install --no-dev

      - name: Install Jack's Botan Distribution GPG public key
        if: ${{ env.BUILDING_RELEASE == 'true' }}
        run: gpg --trusted-key 6211EBF1EFBADFBC --import ${{ github.workspace }}/source/.github/resources/jack-botan-release-key.gpg

      - name: Fetch Botan Repository
        uses: actions/checkout@v4
        if: ${{ env.BUILDING_RELEASE == 'true' }}
        with:
          path: ${{ github.workspace }}/botan
          repository: ${{ env.BOTAN_REPO }}
          fetch-depth: 0
          ref: ${{ env.BOTAN_REF }}

      - name: Check Upstream Release Tarball
        if: ${{ env.BUILDING_RELEASE == 'true' }}
        working-directory: source/tools/tarball_checker
        run: poetry run python3 check.py --source-dir ${{ github.workspace }}/botan --tar-source-dir ${{ github.workspace }}/upstream_tar

  collect_artifacts:
    name: "Collect Submission Artifacts"
    runs-on: ubuntu-latest
    needs:
      - pdf_creation
      - audit_generation
      - utility
      - test_report
      - source_archive

    steps:
      - name: Fetch Audit Repository
        uses: actions/checkout@v4
        with:
          path: ./source

      - name: Setup Environment Configuration
        uses: ./source/.github/actions/setup-environment
        with:
          env_file: ./source/config/botan.env

      - name: Fetch Botan Documentation
        uses: actions/download-artifact@v4
        with:
          name: documentation
          path: staging/botandocs

      - name: Split API Documentation and Handbook
        run: |
          mkdir -p 'final/API Documentation'
          mkdir -p 'final/Handbuch'
          cp staging/botandocs/*.zip 'final/API Documentation'
          cp staging/botandocs/handbook/*.pdf 'final/Handbuch'

      - name: Fetch Architecture
        uses: actions/download-artifact@v4
        with:
          name: architecture
          path: final/Architecture

      - name: Fetch Audit Method
        uses: actions/download-artifact@v4
        with:
          name: audit_method
          path: final/Audit

      - name: Fetch Audit Report
        uses: actions/download-artifact@v4
        with:
          name: audit_report
          path: final/Audit

      - name: Fetch Coverage Report
        uses: actions/download-artifact@v4
        with:
          name: coverage
          path: final/Coverage Report

      - name: Fetch Cryptographic Documentation
        uses: actions/download-artifact@v4
        with:
          name: cryptodoc
          path: final/Kryptodoc

      - name: Fetch Source Code
        uses: actions/download-artifact@v4
        with:
          name: source
          path: final/Source Code

      - name: Fetch Test Report
        uses: actions/download-artifact@v4
        with:
          name: testreport
          path: final/Test Report

      - name: Fetch Testspezifikation
        uses: actions/download-artifact@v4
        with:
          name: testspec
          path: final/Testspezifikation

      - name: Upload Bundled Submission Documents
        uses: actions/upload-artifact@v4
        with:
          name: Submission Bundle for Botan ${{ env.BOTAN_VERSION }}
          path: final/*