Supported GitHub Events

    # Start background task immediately using asyncio.create_task
    # This ensures the HTTP response is sent immediately without waiting
    # Store task reference for observability and graceful shutdown
    task = asyncio.create_task(
        process_with_error_handling(
            _hook_data=hook_data,
            _headers=request.headers,
            _delivery_id=delivery_id,
            _event_type=event_type,
        )
    )
    _background_tasks.add(task)
    task.add_done_callback(_background_tasks.discard)

    # Return 200 immediately with JSONResponse for fastest serialization
    return JSONResponse(
        status_code=status.HTTP_200_OK,
        content={
            "status": status.HTTP_200_OK,
            "message": "Webhook queued for processing",
            "delivery_id": delivery_id,
            "event_type": event_type,
        },
    )

    events: # To listen to all events do not send events
      - push
      - pull_request
      - pull_request_review
      - pull_request_review_thread
      - issue_comment
      - check_run
      - status

            # Skip branch/tag deletions - no processing needed
            if self.hook_data.get("deleted"):
                self.logger.info(f"{self.log_prefix} Branch/tag deletion detected, skipping processing")
                token_metrics = await self._get_token_metrics()
                self.logger.info(
                    f"{self.log_prefix} Webhook processing completed: deletion event (skipped) - {token_metrics}"
                )
                await self._update_context_metrics()
                return None

            ref = self.hook_data["ref"]

            # Only clone for tag pushes - branch pushes don't require cloning
            # because PushHandler only processes tags (PyPI upload, container build)
            if ref.startswith("refs/tags/"):
                await self._clone_repository(checkout_ref=ref)
                await PushHandler(github_webhook=self).process_push_webhook_data()
                token_metrics = await self._get_token_metrics()
                self.logger.info(
                    f"{self.log_prefix} Webhook processing completed successfully: push - {token_metrics}",
                )
            else:
                self.logger.debug(f"{self.log_prefix} Skipping clone for branch push: {ref}")
                token_metrics = await self._get_token_metrics()
                self.logger.info(
                    f"{self.log_prefix} Webhook processing completed: branch push (skipped) - {token_metrics}"
                )

        setup_tasks.append(self.owners_file_handler.assign_reviewers(pull_request=pull_request))
        setup_tasks.append(
            self.labels_handler._add_label(
                pull_request=pull_request,
                label=f"{BRANCH_LABEL_PREFIX}{pull_request.base.ref}",
            )
        )
        setup_tasks.append(self.label_pull_request_by_merge_state(pull_request=pull_request))
        setup_tasks.append(self.check_run_handler.set_check_queued(name=CAN_BE_MERGED_STR))

        # Only queue built-in checks when their corresponding feature is enabled
        if self.github_webhook.tox:
            setup_tasks.append(self.check_run_handler.set_check_queued(name=TOX_STR))

        if self.github_webhook.pre_commit:
            setup_tasks.append(self.check_run_handler.set_check_queued(name=PRE_COMMIT_STR))

        if self.github_webhook.pypi:
            setup_tasks.append(self.check_run_handler.set_check_queued(name=PYTHON_MODULE_INSTALL_STR))

        if self.github_webhook.build_and_push_container:
            setup_tasks.append(self.check_run_handler.set_check_queued(name=BUILD_CONTAINER_STR))

        setup_tasks.append(self._process_verified_for_update_or_new_pull_request(pull_request=pull_request))
        setup_tasks.append(self.labels_handler.add_size_label(pull_request=pull_request))
        setup_tasks.append(self.add_pull_request_owner_as_assingee(pull_request=pull_request))

        if self.github_webhook.conventional_title:
            setup_tasks.append(self.check_run_handler.set_check_queued(name=CONVENTIONAL_TITLE_STR))

        # Queue custom check runs (same as built-in checks)
        # Note: custom checks are validated in GithubWebhook._validate_custom_check_runs()
        # so name is guaranteed to exist
        for custom_check in self.github_webhook.custom_check_runs:
            check_name = custom_check["name"]
            setup_tasks.append(self.check_run_handler.set_check_queued(name=check_name))

        self.logger.info(f"{self.log_prefix} Executing setup tasks")
        setup_results = await asyncio.gather(*setup_tasks, return_exceptions=True)

        for result in setup_results:
            if isinstance(result, Exception):
                self.logger.error(f"{self.log_prefix} Setup task failed: {result}")

        if self.ctx:
            self.ctx.complete_step("pr_workflow_setup")

        # Stage 2: CI/CD execution tasks
        if self.ctx:
            self.ctx.start_step("pr_cicd_execution")

        ci_tasks: list[Coroutine[Any, Any, Any]] = []

        ci_tasks.append(self.runner_handler.run_tox(pull_request=pull_request))
        ci_tasks.append(self.runner_handler.run_pre_commit(pull_request=pull_request))
        ci_tasks.append(self.runner_handler.run_install_python_module(pull_request=pull_request))
        ci_tasks.append(self.runner_handler.run_build_container(pull_request=pull_request))

        if self.github_webhook.conventional_title:
            ci_tasks.append(self.runner_handler.run_conventional_title_check(pull_request=pull_request))

        # Launch custom check runs (same as built-in checks)
        for custom_check in self.github_webhook.custom_check_runs:
            ci_tasks.append(
                self.runner_handler.run_custom_check(
                    pull_request=pull_request,
                    check_config=custom_check,
                )
            )

# Commands allowed on draft PRs (optional)
# If not set: commands are blocked on draft PRs (default behavior)
# If empty list []: all commands allowed on draft PRs
# If list with values: only those commands allowed on draft PRs
# allow-commands-on-draft-prs: []  # Uncomment to allow all commands on draft PRs
# allow-commands-on-draft-prs:     # Or allow only specific commands:
#   - build-and-push-container
#   - retest

        # Check if command is allowed on draft PRs
        if is_draft and _command != COMMAND_TEST_ORACLE_STR:
            allow_commands_on_draft = self.github_webhook.config.get_value("allow-commands-on-draft-prs")
            if not isinstance(allow_commands_on_draft, list):
                self.logger.debug(
                    f"{self.log_prefix} Command {_command} blocked: "
                    "draft PR and allow-commands-on-draft-prs not configured"
                )
                return
            # Empty list means all commands allowed; non-empty list means only those commands
            if len(allow_commands_on_draft) > 0:
                # Sanitize: ensure all entries are strings for safe join and comparison
                allow_commands_on_draft = [str(cmd) for cmd in allow_commands_on_draft]
                if _command not in allow_commands_on_draft:
                    self.logger.debug(
                        f"{self.log_prefix} Command {_command} is not allowed on draft PRs. "
                        f"Allowed commands: {allow_commands_on_draft}"
                    )
                    await asyncio.to_thread(
                        pull_request.create_issue_comment,
                        f"Command `/{_command}` is not allowed on draft PRs.\n"
                        f"Allowed commands on draft PRs: {', '.join(allow_commands_on_draft)}",
                    )
                    return

            if self.hook_data["action"] == "submitted":
                """
                Available actions:
                    commented
                    approved
                    changes_requested
                """
                reviewed_user = self.hook_data["review"]["user"]["login"]
                review_state = self.hook_data["review"]["state"]
                self.github_webhook.logger.debug(
                    f"{self.github_webhook.log_prefix} "
                    f"Processing pull request review for user {reviewed_user} with state {review_state}"
                )

                await self.labels_handler.manage_reviewed_by_label(
                    pull_request=pull_request,
                    review_state=review_state,
                    action=ADD_STR,
                    reviewed_user=reviewed_user,
                )

                if body := self.hook_data["review"]["body"]:
                    self.github_webhook.logger.debug(f"{self.github_webhook.log_prefix} Found review body: {body}")
                    # In this project, "approved" means a maintainer uses the /approve command
                    # (which adds an approved-<user> label), NOT GitHub's review approval state.
                    # The oracle trigger fires only when /approve is found in the review body.
                    if any(line.strip() == f"/{APPROVE_STR}" for line in body.splitlines()):
                        await self.labels_handler.label_by_user_comment(
                            pull_request=pull_request,
                            user_requested_label=APPROVE_STR,
                            remove=False,
                            reviewed_user=reviewed_user,
                        )
                        task = asyncio.create_task(
                            call_test_oracle(
                                github_webhook=self.github_webhook,
                                pull_request=pull_request,
                                trigger="approved",
                            )
                        )
                        _background_tasks.add(task)
                        task.add_done_callback(_background_tasks.discard)

        if self.hook_data.get("action", "") != "completed":
            self.logger.debug(
                f"{self.log_prefix} check run {check_run_name} action is "
                f"{self.hook_data.get('action', 'N/A')} and not completed, skipping"
            )
            if self.ctx:
                self.ctx.complete_step("check_run_handler")
            return False

        check_run_status: str = _check_run["status"]
        check_run_conclusion: str = _check_run["conclusion"]
        self.logger.debug(
            f"{self.log_prefix} processing check_run - Name: {check_run_name} "
            f"Status: {check_run_status} Conclusion: {check_run_conclusion}"
        )

        if check_run_name == CAN_BE_MERGED_STR:
            if getattr(self, "labels_handler", None) and pull_request and check_run_conclusion == SUCCESS_STR:
                if await self.labels_handler.label_exists_in_pull_request(
                    label=AUTOMERGE_LABEL_STR, pull_request=pull_request
                ):
                    try:
                        await asyncio.to_thread(pull_request.merge, merge_method="SQUASH")
                        self.logger.info(
                            f"{self.log_prefix} Successfully auto-merged pull request #{pull_request.number}"
                        )
                        if self.ctx:
                            self.ctx.complete_step("check_run_handler")
                        return False
                    except Exception as ex:
                        self.logger.error(
                            f"{self.log_prefix} Failed to auto-merge pull request #{pull_request.number}: {ex}"
                        )
                        if self.ctx:
                            self.ctx.complete_step("check_run_handler")
                        return True

            else:
                self.logger.debug(f"{self.log_prefix} check run is {CAN_BE_MERGED_STR}, skipping")
                if self.ctx:
                    self.ctx.complete_step("check_run_handler")
                return False

        if self.ctx:
            self.ctx.complete_step("check_run_handler")
        return True

    branch-protection:
      strict: True
      require_code_owner_reviews: True
      dismiss_stale_reviews: False
      required_approving_review_count: 1
      required_linear_history: True
      required_conversation_resolution: True

# GitHub events to listen to
events:
  - push
  - pull_request
  - pull_request_review
  - pull_request_review_comment
  - pull_request_review_thread
  - issue_comment
  - check_run
  - status