main.yml

# This code is a Qiskit project.
#
# (C) Copyright IBM 2023.
#
# This code is licensed under the Apache License, Version 2.0. You may
# obtain a copy of this license in the LICENSE file in the root directory
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
#
# Any modifications or derivative works of this code must retain this
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

name: Pull request
on: [pull_request, merge_group]
jobs:
  decide-jobs:
    name: Decide which jobs to run
    runs-on: ubuntu-latest
    if: github.repository_owner == 'Qiskit'
    outputs:
      all-changed-files: ${{ steps.changed-files.outputs.ALL_CHANGED_FILES }}
      run-notebook-tester: ${{ steps.decide.outputs.RUN_NOTEBOOK_TESTER }}
      run-api-checks: ${{ steps.decide.outputs.RUN_API_CHECKS }}
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Determine all changed files
        id: changed-files
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          # GitHub API doesn't give PR information in the merge_group event, but
          # we can get the PR number from the branch name
          if [[ "${{ github.event_name }}" == 'merge_group' ]]; then
            BRANCH_NAME="$(git rev-parse --abbrev-ref HEAD)"
            PR_NUMBER="$(echo $BRANCH_NAME | grep -oP '(?<=gh-readonly-queue/main/pr-)\d+')"
          else
            PR_NUMBER="${{ github.event.number }}"
          fi

          CHANGED_FILES=$(node scripts/ci/determine-changed-files.ts "${PR_NUMBER}")
          {
            echo "ALL_CHANGED_FILES<<__GH_OUTPUT__"
            printf '%s\n' "$CHANGED_FILES"
            echo "__GH_OUTPUT__"
          } >> "$GITHUB_OUTPUT"
      - name: Decide which jobs to run
        id: decide
        env:
          CHANGED_FILES: ${{ steps.changed-files.outputs.ALL_CHANGED_FILES }}
          # If changing these regexes, test them on https://regex101.com/ with the
          # following paths (you can paste the block in and uncomment it):
          # Add new tests if necessary
          NOTEBOOK_TEST_REGEX: (\.github\/workflows\/main\.yml|(docs|learning)(?!\/api\/)\/.*\.ipynb|scripts\/nb-tester\/.*)
          #  -- Should match:
          #  .github/workflows/main.yml
          #  scripts/nb-tester/requirements.txt
          #  docs/guides/thing.ipynb
          #  learning/courses/my-course/notebook.ipynb
          #
          #  -- Should not match:
          #  docs/guides/thing.mdx
          #  docs/api/thing.mdx
          #  docs/api/thing.ipynb
          #  scripts/js/lib/thing.ts

          API_CHECKS_REGEX: (\.github\/workflows\/main\.yml|(docs\/api|public\/docs\/api|scripts\/js)\/.*)
          #  -- Should match:
          #  docs/api/qiskit/index.mdx
          #  public/docs/api/qiskit-ibm-runtime/objects.inv
          #  public/docs/api/qiskit/thing.avif
          #  scripts/js/lib/links/thing.ts
          #  .github/workflows/main.yml
          #
          #  -- Should not match:
          #  scripts/nb-tester/file.py
          #  docs/guides/thing.ipynb
          #  public/learning/image.svg
          #  .github/workflows/notebook-test-cron.yml
        run: |
          if [[ "${{ github.event_name }}" == 'pull_request' && -n "$(printf '%s\n' "${CHANGED_FILES}" | grep -P "$NOTEBOOK_TEST_REGEX")" ]]; then
            echo "RUN_NOTEBOOK_TESTER=true" >> "$GITHUB_OUTPUT"
          fi
          if [[ "${{ github.event_name }}" == 'pull_request' && -n "$(printf '%s\n' "${CHANGED_FILES}" | grep -P "$API_CHECKS_REGEX")" ]]; then
            echo "RUN_API_CHECKS=true" >> "$GITHUB_OUTPUT"
          fi

  lint:
    name: Lint
    runs-on: ubuntu-latest
    if: github.repository_owner == 'Qiskit'
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Install Node.js dependencies
        run: npm ci
      - name: Install ImageMagick
        run: |
          sudo apt-get install -y imagemagick
          sudo ln -s /usr/bin/convert /usr/bin/magick
      - name: Install Playwright
        run: npx playwright install

      - name: Check markdown
        run: npm run check:markdown
      - name: Spellcheck
        run: npm run check:spelling
      - name: Check Qiskit bot config
        run: npm run check:qiskit-bot
      - name: Check Patterns index
        run: npm run check:patterns-index
      - name: Check tutorials index
        run: python scripts/ci/check-tutorials-index.py
      - name: Internal link checker
        run: npm run check:internal-links
      - name: Check orphaned pages
        run: npm run check:orphan-pages
      - name: Check stale images
        run: npm run check:stale-images
      - name: Formatting
        run: npm run check:fmt
      - name: Typecheck
        run: npm run typecheck
      - name: Infrastructure tests
        run: npm test

      - name: Get all changed content files
        env:
          CHANGED_FILES: ${{needs.decide-jobs.outputs.all-changed-files}}
          # If changing these regexes, test them on https://regex101.com/ with the
          # following paths (you can paste the block in and uncomment it):
          # Add new tests if necessary
          CONTENT_FILE_REGEX: (docs|learning)\/.*\.(mdx|ipynb)$
          #  -- Should match:
          #  docs/guides/thing.ipynb
          #  docs/guides/thing.mdx
          #  docs/api/qiskit/index.mdx
          #  learning/courses/my-course/introduction.ipynb
          #
          #  -- Should not match:
          #  docs/guides/_toc.json
          #  scripts/nb-tester/example-notebook.ipynb
        id: changed-content-files
        run: |
          CHANGED_CONTENT_FILES=$(echo "${CHANGED_FILES}" | grep -P $CONTENT_FILE_REGEX || true)
          if [ "$CHANGED_CONTENT_FILES" != '' ]
          then
            echo "ANY_CHANGED=true" >> "$GITHUB_OUTPUT"
          fi
          mkdir -p .github/outputs
          echo $CHANGED_CONTENT_FILES >> .github/outputs/changed-content-files.txt
      - name: Pull preview image
        if: steps.changed-content-files.outputs.ANY_CHANGED == 'true'
        run: ./start --pull-only
      - name: Start local Docker preview (cloud app)
        if: steps.changed-content-files.outputs.ANY_CHANGED == 'true'
        run: |
          ./start --apis &
          sleep 1
      - name: Check that pages render
        if: steps.changed-content-files.outputs.ANY_CHANGED == 'true'
        run: |
          npm run check:pages-render -- --from-file .github/outputs/changed-content-files.txt
      - name: Check that Katex expressions render
        if: steps.changed-content-files.outputs.ANY_CHANGED == 'true'
        run: |
          npm run check:katex-render -- --from-file .github/outputs/changed-content-files.txt
      - name: Stop Docker preview
        if: steps.changed-content-files.outputs.ANY_CHANGED == 'true'
        run: docker ps -q | xargs docker stop

      - name: Setup Python environment
        uses: ./.github/actions/set-up-notebook-testing
        with:
          ibm-cloud-token: ${{ secrets.IBM_CLOUD_TEST_TOKEN }}
          instance: ${{ vars.IBM_CLOUD_TEST_CRN }}

      - name: Check all notebooks are listed in the config file
        run: python scripts/ci/check-all-notebooks-are-tested.py

      - name: Lint notebooks
        if: steps.changed-content-files.outputs.ANY_CHANGED == 'true'
        shell: python
        run: |
          import subprocess, sys
          try:
            subprocess.run(["tox", "-e", "lint"], check=True)
          except:
            print(
              "Error while linting notebook. "
              "To fix, install tox and run `tox -e fix`."
            )
            sys.exit(1)

  notebook-test:
    name: Execute notebooks
    needs: [decide-jobs]
    if: github.repository_owner == 'Qiskit' && needs.decide-jobs.outputs.run-notebook-tester == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get changed files
        env:
          CHANGED_FILES: ${{needs.decide-jobs.outputs.all-changed-files}}
        run: |
          mkdir -p .github/outputs
          echo "${CHANGED_FILES}" > .github/outputs/changed-files.txt

      - name: Check if extra linux deps needed
        id: check-deps
        shell: python
        env:
          # Add your notebook to this list if it needs latex or graphviz to run
          EXTRA_DEPS_NOTEBOOKS: |
            docs/guides/visualize-circuits.ipynb
            docs/guides/custom-backend.ipynb
            docs/guides/transpiler-stages.ipynb
            docs/guides/represent-quantum-computers.ipynb
            docs/guides/common-parameters.ipynb
            docs/guides/DAG-representation.ipynb
        run: |
          import os
          from pathlib import Path

          extra_deps_notebooks = """${{ env.EXTRA_DEPS_NOTEBOOKS }}""".strip().split("\n")
          github_output = os.getenv("GITHUB_OUTPUT")
          all_files = Path(".github/outputs/changed-files.txt").read_text().split("\n")

          config_changed = any(path.startswith("scripts/") or path.startswith(".github") for path in all_files)
          extra_deps = config_changed or any(path in extra_deps_notebooks for path in all_files)

          with open(github_output, "a") as output:
            output.write(f"NEEDS_EXTRA_DEPS={str(extra_deps).lower()}")

      - name: Setup environment
        uses: ./.github/actions/set-up-notebook-testing
        with:
          # Install Linux deps if the specific guides were changed, or
          # if all files are being tested.
          install-linux-deps: ${{ steps.check-deps.outputs.NEEDS_EXTRA_DEPS }}
          ibm-cloud-token: ${{ secrets.IBM_CLOUD_TEST_TOKEN }}
          instance: ${{ vars.IBM_CLOUD_TEST_CRN }}

      - name: Execute notebooks
        env:
          PR_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
        run: python scripts/ci/pr-execute-notebooks.py

      - name: Detect changed notebooks
        id: changed-notebooks
        run: |
          echo "CHANGED_NOTEBOOKS<<EOF" >> $GITHUB_OUTPUT
          git diff --name-only >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Upload executed notebooks
        uses: actions/upload-artifact@v4
        with:
          name: Executed notebooks
          path: ${{ steps.changed-notebooks.outputs.CHANGED_NOTEBOOKS || 'no-changes' }}

  api-checks:
    name: API checks
    needs: [decide-jobs]
    runs-on: ubuntu-latest
    if: github.repository_owner == 'Qiskit' && needs.decide-jobs.outputs.run-api-checks == 'true'
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Install Node.js dependencies
        run: npm ci
      - name: Check internal links
        run: >
          npm run check:internal-links --
          --current-apis
          --dev-apis
          --historical-apis
          --qiskit-legacy-release-notes
      - name: Check for orphan pages
        run: npm run check:orphan-pages -- --apis
      - name: Check markdown
        run: npm run check:markdown -- --apis