QAPI Integration for Python Microservices

SeeR — QAPI integration with GitHub Actions for continuous impact analysis on Python projects.

This document walks you through everything you need to connect SeeR (QAPI) to a GitHub repository so that API impact analysis runs automatically on Pull Requests. It includes step‑by‑step setup, the recommended GitHub Actions workflow, secrets required, policy guidance (no shell scripts in PRs), troubleshooting, and FAQs.

Table of contents

• Summary

• Prerequisites

• 1) Create a GitHub Personal Access Token (PAT)

• 2) Add the GitHub Actions workflow (code-impact.yml)

• 3) Configure repository secrets

• Best practices & policy

  • Policy: No shell scripts (.sh) in PRs

  • Checklist before creating a PR

• Troubleshooting

---

Summary

Quick overview

• Runs QAPI impact analysis on Pull Requests to your integration branch.

• Publishes results as GitHub Issues with the impact-analysis label.

• Requires a PAT, GitHub Actions workflow, and repository secrets.

Once configured, your repository will trigger SeeR's QAPI impact analysis whenever a Pull Request targets your chosen integration branch (for example develop or main). Results are published as GitHub Issues (label impact-analysis) and visible in the Actions tab.

Prerequisites

• A GitHub repository containing your Python API code and OpenAPI specs.

• Admin permissions (or repo settings access) to add Actions/workflows and repository secrets.

• Basic familiarity with GitHub Actions and branching/PR workflows.

---

1) Create a GitHub Personal Access Token (PAT)

You will need a PAT so QAPI can interact with the repository. Create one with the scopes below.

Steps:

1. Go to GitHub: Settings > Developer settings > Personal access tokens > Tokens (classic).

2. Click Generate new token (classic).

3. Add a descriptive name (for example: SeeR-QAPI-Python-integration).

4. Set an expiration according to your security policy (recommended).

5. Select scopes:

   • repo (Full control of private repositories)

   • workflow (Read/write GitHub Actions workflows)

   • admin:repo_hook (Manage webhooks)

   • read:org (Optional: read org metadata)

6. Generate the token and copy it somewhere secure. You will add it to the repository secrets in Step 3.

Tip: Store the PAT in your team's password manager so it can be rotated safely.

---

2) Add the GitHub Actions workflow (code-impact.yml)

Create the folder .github/workflows/ (if it doesn't exist) and add code-impact.yml with the content below. Update the target branch name (e.g., develop) and secret names as required by your environment.

# .github/workflows/code-impact.yml
name: Python Code Impact Analysis

on:
  pull_request:
    branches:
      - develop # <-- change to your integration branch (main/master/staging)
    types: [opened, synchronize, reopened]

permissions:
  contents: write
  issues: write
  pull-requests: read

jobs:
  analyze-code-impact:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install requests

      - name: Get changed files info
        id: files
        run: |
          git fetch origin develop
          echo "Changed files (vs origin/develop):"
          git diff --name-status origin/develop HEAD > changed_files.txt
          cat changed_files.txt

      - name: Qyrus Python Impact Analysis
        id: impact
        uses: vatsalQ/qyrus-impact-analyzer-py@v2
        with:
          impact_api_url:   ${{ secrets.IMPACT_API_URL }}
          api_access_token: ${{ secrets.API_ACCESS_TOKEN }}
          project_id:       ${{ secrets.PROJECT_ID || '' }}
          workspace_name:   ${{ secrets.WORKSPACE_NAME }}
          suite_name:       ${{ secrets.SUITE_NAME }}
          environment_name: ${{ secrets.ENVIRONMENT_NAME }}
          username:         ${{ secrets.USERNAME }}
          password:         ${{ secrets.PASSWORD }}
          github_token:     ${{ secrets.GITHUB_TOKEN }}

      - name: Wait for Qyrus Impact Analysis issue
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          LABEL="impact-analysis"
          MAX_SEC=$((45*60))
          SLEEP=15

          BASE_COUNT=$(gh issue list --state all --label "$LABEL" --limit 1000 --json number --jq 'length')
          echo "Found $BASE_COUNT existing '$LABEL' issue(s)."

          elapsed=0
          while [ $elapsed -lt $MAX_SEC ]; do
            CUR_COUNT=$(gh issue list --state all --label "$LABEL" --limit 1000 --json number --jq 'length')
            if [ "$CUR_COUNT" -gt "$BASE_COUNT" ]; then
              echo "✅ New Impact Analysis issue detected!"
              exit 0
            fi
            sleep $SLEEP
            elapsed=$((elapsed+SLEEP))
          done

          echo "❌ Timed out waiting for Impact Analysis issue." >&2
          exit 1

How this workflow works (brief)

• Triggers on PR events targeting your integration branch.

• Checks out the full repository history to compute diffs.

• Runs the Qyrus impact analyzer action and waits for the analysis to publish a GitHub Issue labeled impact-analysis.

---

3) Configure repository secrets

In the repository: Settings > Secrets > Actions add the following secrets (names, example values, and descriptions):

Secret Name	Example Value	Description
IMPACT_API_URL	https://stg-gateway.qyrus.com:8243/impact-dispatcher/v1/analyze-impact	The endpoint for the Python Impact Analyzer service that SeeR (QAPI) communicates with.
API_ACCESS_TOKEN	Bearer 90540897-748a-3ef2-b3a3-c6f8f42022da	Your authentication token for the Qyrus gateway.
GITHUB_TOKEN	YOUR_GENERATED_PAT_FROM_STEP_1	The GitHub Personal Access Token you generated in Step 1.
WORKSPACE_NAME	MyTeamWorkspace	Your workspace name in QAPI.
SUITE_NAME	RegressionSuite	The name of the test suite in QAPI where your APIs are present.
ENVIRONMENT_NAME	Global Default	The environment name in QAPI for test execution.
USERNAME	[email protected]	Your username for logging into QAPI.
PASSWORD	securePassword123!	Your password for logging into QAPI.

Note: Never hard-code secrets in workflow files or source code.

---

Best practices & policy

⚠️ Policy: No shell scripts (.sh) in PRs

Before opening a Pull Request for QAPI integration, ensure that there are no shell scripts (files ending in .sh, e.g., start.sh) present in either the source or the target branch.

Why:

• Security: Executable scripts in branches may run arbitrary commands and increase risk.

• Portability: CI runners differ; workflows provide a consistent, documented environment.

• Predictability: Centralizing build/run steps in workflow files reduces surprises during CI.

• Risk of abuse: Shell scripts can be used to gain system access or inject malicious code (see React2Shell).

Checklist before creating a PR:

• Remove any *.sh files from the source branch.

• Confirm the target branch does not have the same *.sh file you are reintroducing.

• Express build/run steps via .github/workflows/* instead of adding ad-hoc scripts.

---

Troubleshooting

• Problem: Workflow times out waiting for impact-analysis issue.

  • Check that the IMPACT_API_URL and API_ACCESS_TOKEN secrets are correct and reachable from the runner.

  • Inspect the Qyrus Python Impact Analysis step logs for errors.

• Problem: Action fails to checkout or compute diffs.

  • Ensure fetch-depth: 0 is set on actions/checkout so git history is available.

• Problem: Missing permissions to create issues.

  • Confirm the workflow permissions include issues: write and that the PAT has required scopes.

---

Done! SeeR (via QAPI) is Now Linked to GitHub!

Once these steps are complete:

• Automated tests will trigger based on your workflow configuration (e.g., with every commit if you set on: push).

• You’ll see the reports and results directly as new GitHub Issues (with the impact-analysis label) and in the GitHub Actions tab, providing immediate feedback on your code changes!