إضافة الـ runner إلى خط أنابيب CI لديك

يُجرى التحليل في خط أنابيب CI حيث يوجد كودك بالفعل - أي إن كودك المصدري لا يغادر بنيتك التحتية أبدًا. في الأمثلة أدناه، يُستدعى الـ runner باستخدام الرمز المميز الخاص بالمشروع.

ملاحظة

عرّف APPARCH_TOKEN كمتغيّر سرّي/محميّ في CI لديك. اختَر صورة الـ runner حسب اللغة (مثل collectors/dotnet وcollectors/python وcollectors/go).

تسحب جميع الأمثلة الصورة من AppArch Hub؛ راجع تلك الصفحة للمصادقة ومطابقة اللغة والأخطاء الشائعة.

GitHub Actions

.github/workflows/apparch.yml

name: AppArch
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # the target branch is then in the clone: the change's own files and its merge base
      - run: |
          echo "$APPARCH_INSTALLATION_KEY" | docker login hub.apparch.io -u "$APPARCH_INSTALLATION_ID" --password-stdin
          docker run --rm -v "$PWD:/workspace:ro" \
            -e APPARCH_Collector__Token="$APPARCH_TOKEN" \
            -e APPARCH_Collector__ApiUrl="https://api.yourdomain.com" \
            -e GITHUB_EVENT_NAME -e GITHUB_REF -e GITHUB_REPOSITORY \
            -e GITHUB_SERVER_URL -e GITHUB_BASE_REF -e GITHUB_SHA \
            hub.apparch.io/collectors/dotnet:latest /workspace
        env:
          APPARCH_TOKEN: ${{ secrets.APPARCH_TOKEN }}
          APPARCH_INSTALLATION_ID: ${{ secrets.APPARCH_INSTALLATION_ID }}
          APPARCH_INSTALLATION_KEY: ${{ secrets.APPARCH_INSTALLATION_KEY }}

GitLab CI

# Image pulls are authorized with your INSTALLATION credential, not the project token
# (Settings → CI/CD → Variables):
#   DOCKER_AUTH_CONFIG = {"auths":{"hub.apparch.io":{"auth":"base64(<installation-id>:<installation-key>)"}}}
archpilot:
  image: hub.apparch.io/collectors/dotnet:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    APPARCH_Collector__Token: "$APPARCH_TOKEN"
    APPARCH_Collector__ApiUrl: "https://api.yourdomain.com"
  script:
    # Optional flags: --modules archpilot,archscan (pin what runs)
    # --modules archpilot alone reads ONLY the merge request's changed files - the fast option
    # for MR pipelines; archscan / archsecurity are repository reports and read everything.
    #                 --fail-on critical (fail this step when findings at/above the level exist)
    - apparch "$CI_PROJECT_DIR"

Bitbucket Pipelines

pipelines:
  pull-requests:
    '**':
      - step:
          image:
            name: hub.apparch.io/collectors/dotnet:latest
            username: $APPARCH_INSTALLATION_ID
            password: $APPARCH_INSTALLATION_KEY
            run-as-user: 0   # the clone belongs to root; a PR run fetches the target branch into it
          script:
            - export APPARCH_Collector__Token="$APPARCH_TOKEN"
            - export APPARCH_Collector__ApiUrl="https://api.yourdomain.com"
            - apparch "$BITBUCKET_CLONE_DIR"

Azure DevOps

trigger: none
pr: ['*']
pool: { vmImage: ubuntu-latest }
steps:
  - checkout: self
    fetchDepth: 0   # the target branch is then in the clone: the change's own files and its merge base
  - script: |
      echo "$(APPARCH_INSTALLATION_KEY)" | docker login hub.apparch.io -u "$(APPARCH_INSTALLATION_ID)" --password-stdin
      docker run --rm -v "$(Build.SourcesDirectory):/workspace:ro" \
        -e APPARCH_Collector__Token="$(APPARCH_TOKEN)" \
        -e APPARCH_Collector__ApiUrl="https://api.yourdomain.com" \
        -e SYSTEM_PULLREQUEST_PULLREQUESTID="$(System.PullRequest.PullRequestId)" \
        -e SYSTEM_PULLREQUEST_TARGETBRANCH="$(System.PullRequest.TargetBranch)" \
        -e SYSTEM_TEAMPROJECT="$(System.TeamProject)" \
        -e BUILD_REPOSITORY_NAME="$(Build.Repository.Name)" \
        -e SYSTEM_COLLECTIONURI="$(System.CollectionUri)" \
        -e BUILD_SOURCEVERSION="$(Build.SourceVersion)" \
        hub.apparch.io/collectors/dotnet:latest /workspace

Jenkins

pipeline {
  agent { docker { image 'hub.apparch.io/collectors/dotnet:latest' registryUrl 'https://hub.apparch.io' registryCredentialsId 'apparch-hub' } }
  environment {
    APPARCH_Collector__Token = credentials('APPARCH_TOKEN')
    APPARCH_Collector__ApiUrl = 'https://api.yourdomain.com'
    // PR review (ArchPilot) needs the MR context set explicitly; without these the run is a full scan (ArchScan).
    APPARCH_Collector__Provider__Type = 'gitlab' // gitlab | github | bitbucket | azuredevops
    APPARCH_Collector__Provider__ProjectId = 'group/project'
    APPARCH_Collector__Provider__PullRequestId = "${env.CHANGE_ID}"
  }
  stages {
    stage('AppArch') {
      steps {
        sh 'apparch "$WORKSPACE"'
      }
    }
  }
}

في المرة التالية التي يُفتح فيها PR/MR، يترك ArchPilot تعليقات سطرًا بسطر. يختار الـ runner الوضع تلقائيًا: في خط أنابيب PR/MR تعمل المراجعة السريعة (ArchPilot)، وفي خط أنابيب push يعمل الفحص الكامل (ArchScan).

مستخدم الحاوية

تعمل صور الـ collector بمستخدم غير جذري (uid 10001) وتقرأ نسخة المستودع فقط، حتى لو كانت مملوكة لمستخدم آخر. في طلب السحب يقارن الـ collector التغيير بالفرع الهدف (ملفات التغيير نفسه وقاعدة الدمج)، لذلك يجب أن يكون هذا الفرع موجودًا في النسخة:

• GitHub Actions وAzure DevOps: تجلب الأمثلة السجل كاملًا (fetch-depth: 0، fetchDepth: 0)، فيكون الفرع الهدف موجودًا ولا يُكتب شيء.
• GitLab CI وJenkins: تعمل كما هي (نسخة GitLab قابلة للكتابة للمهمة، وJenkins يشغّل الحاوية بمستخدمه).
• Bitbucket Pipelines: النسخة مملوكة دائمًا للجذر ويجلب الـ collector الفرع الهدف إليها، لذلك يشغّل المثال الخطوة كجذر (run-as-user: 0).

بدون ذلك تنجح الخطوة أيضًا، لكنها تراجع كل النتائج بدل نتائج التغيير وتتخطى الفحوص التي تقارن بالفرع الهدف (صلاحية أُزيلت، دورة اعتماد جديدة). إذا كان الـ runner لديك يصرّ على الجذر في مكان آخر فاذكر ذلك صراحةً: docker run --user 0 ...، أو securityContext.runAsUser: 0 في Kubernetes.

الشهادات الموقّعة ذاتيًا أو الصادرة عن CA داخلية

إذا كان تثبيت AppArch لديك يُقدَّم بشهادة لا يثق بها منفّذ CI - سلطة شهادات داخلية أو شهادة موقّعة ذاتيًا - فسيفشل التشغيل عند جلب كتالوج القواعد بخطأ TLS. هناك مخرجان، مرتّبان حسب الأفضلية:

1. اجعل الـ CA موثوقة داخل صورة المنفّذ. عندها تُتحقَّق الشهادة كأي شهادة أخرى ولا يتغيّر شيء في المجمّع.
2. عطّل التحقق عبر SslVerify:

SslVerify=false                     # أو SSL_VERIFY أو APPARCH_Collector__SslVerify

القيم false و0 وno وoff تعطّله؛ وأي قيمة أخرى - بما فيها الفارغة - تُبقيه مفعّلًا. ويقبل مجمّع .NET أيضًا الخيار --no-ssl-verify. ويطبع كل تشغيل ssl verify on أو ssl verify OFF - server certificate not checked في كتلة الإقلاع.

تنبيه

مع تعطيل التحقق لا يستطيع المجمّع تمييز Api الخاص بك عن أي شيء يستجيب على ذلك العنوان: فيذهب رمز المشروع والنتائج معًا إلى من يستمع. استخدمه حين يتعذّر الوثوق بالـ CA، لا كإعداد افتراضي.