Define reusable execution environments

(No translation needed, as this is an empty HTML div) (Empty)

منصة	أمر
Linux (curl)	`curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh \
Linux (snap)	`sudo snap install circleci`
macOS (Homebrew)	`brew install circleci`
macOS (curl)	`curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh \
Windows (Chocolatey)	`choco install circleci-cli`
Windows (Scoop)	`scoop install circleci`
Verify Installation	`circleci version`
Initial Setup	`circleci setup`
Update CLI	`circleci update`

أمر	وصف
`circleci config validate`	Validate your `.circleci/config.yml` file
`circleci config validate -c path/to/config.yml`	تحقق من صحة ملف تكوين محدد
`circleci config process .circleci/config.yml`	معالجة وتوسيع التكوين (حل الأوربس)
`circleci local execute`	قم بتنفيذ وظيفة محليًا باستخدام Docker
`circleci local execute --job job-name`	قم بتنفيذ مهمة محددة محليًا
`circleci follow`	قائمة بجميع المشاريع المتابعة
`circleci follow github/org/repo`	اتبع مشروعًا محددًا
`circleci project info github/org/repo`	احصل على معلومات المشروع
`circleci pipeline run github/org/repo`	تشغيل أنبوب جديد
`circleci pipeline run github/org/repo --branch develop`	تشغيل خط الأنابيب على فرع محدد
`circleci pipeline list github/org/repo`	قائمة الأنابيب الحديثة لمشروع
`circleci pipeline get <pipeline-id>`	احصل على تفاصيل حول أنبوب محدد
`circleci build list github/org/repo`	قائمة الإصدارات الحديثة لمشروع
`circleci build get <build-number>`	احصل على معلومات حول بناء محدد
`circleci build cancel <build-number>`	إلغاء بناء جارٍ

أمر	وصف
`circleci pipeline run github/org/repo --parameters '{"key":"value"}'`	تشغيل خط الأنابيب بمعاملات
`circleci local execute --env VAR1=value1 --env VAR2=value2`	قم بالتنفيذ محليًا باستخدام متغيرات البيئة
`circleci context list github org-name`	قائمة جميع السياقات للمؤسسة
`circleci context create github org-name context-name`	إنشاء سياق جديد
`circleci context show github org-name context-name`	إظهار تفاصيل السياق
`circleci context delete github org-name context-name`	احذف سياقًا
`circleci context env-var list github org-name context-name`	سرد المتغيرات البيئية في سياق
`circleci context env-var store github org-name context-name VAR_NAME`	تخزين متغير البيئة في السياق
`circleci orb list`	قائمة بجميع الأوامر العامة المتاحة
`circleci orb search <query>`	ابحث عن الكرات الضوئية حسب الكلمة المفتاحية
`circleci orb info namespace/orb@version`	احصل على معلومات مفصلة حول orb
`circleci orb source namespace/orb@version`	عرض الكود المصدري لـ orb
`circleci orb create namespace/orb`	أنشئ مجالًا جديدًا
`circleci orb publish path/to/orb.yml namespace/orb@dev:first`	نشر النسخة التطويرية لـ orb
`circleci orb publish promote namespace/orb@dev:first patch`	ارفع orb إلى الإنتاج (إصدار التصحيح)
`circleci orb validate path/to/orb.yml`	التحقق من تكوين Orb
`circleci api graphql-query --query '{ me { id name } }'`	نفذ استعلام GraphQL API
`circleci api get /me`	قم بإرسال طلب GET لواجهة برمجة التطبيقات REST
`circleci diagnostic`	قم بإجراء فحوصات تشخيصية على إعداد CLI
`circleci config pack src/ > orb.yml`	حزم ملفات مصدر orb في ملف YAML واحد
`.circleci/config.yml`## الاستخدام المتقدم

version: 2.1

# Define reusable execution environments
executors:
  node-executor:
    docker:
      - image: cimg/node:18.16
    resource_class: medium
    working_directory: ~/project

# Define reusable command sequences
commands:
  install-deps:
    steps:
      - restore_cache:
          keys:
            - v1-deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - save_cache:
          key: v1-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules

# Define jobs
jobs:
  build:
    executor: node-executor
    steps:
      - checkout
      - install-deps
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist

  test:
    executor: node-executor
    steps:
      - checkout
      - install-deps
      - run: npm test
      - store_test_results:
          path: test-results

# Define workflows
workflows:
  build-and-test:
    jobs:
      - build
      - test:
          requires:
            - build
```## الإعدادات

### هيكل ملف الإعدادات الأساسي

يوجد ملف إعدادات CircleCI في 
`.circleci/config.yml` في جذر المستودع.
```yaml
jobs:
  build:
    docker:
      - image: cimg/python:3.11
        auth:
          username: $DOCKERHUB_USERNAME
          password: $DOCKERHUB_PASSWORD
        environment:
          FLASK_ENV: development
      - image: cimg/postgres:14.0
        environment:
          POSTGRES_USER: testuser
          POSTGRES_DB: testdb
    resource_class: large
    steps:
      - checkout
      - run: python app.py
```### تكوين Docker Executor
```yaml
jobs:
  build:
    machine:
      image: ubuntu-2204:2023.04.2
      docker_layer_caching: true
    resource_class: large
    steps:
      - checkout
      - run: docker build -t myapp .
```### تكوين Machine Executor
```yaml
version: 2.1

orbs:
  node: circleci/node@5.1.0
  aws-cli: circleci/aws-cli@3.1.0
  slack: circleci/slack@4.12.0

jobs:
  deploy:
    executor: node/default
    steps:
      - checkout
      - node/install-packages
      - aws-cli/setup
      - run: npm run deploy
      - slack/notify:
          event: pass
          template: success_tagged_deploy_1
```### استخدام Orbs
```yaml
workflows:
  version: 2
  build-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test
          filters:
            branches:
              only:
                - main
                - /release\/.*/
            tags:
              only: /^v.*/
  
  nightly:
    triggers:
      - schedule:
          cron: "0 0 * * *"
          filters:
            branches:
              only: main
    jobs:
      - test
```### فلاتر سير العمل والجدولة
```yaml
jobs:
  test:
    docker:
      - image: cimg/node:18.16
    parallelism: 4
    steps:
      - checkout
      - run: npm ci
      - run:
          name: Run Tests
          command: |
            TESTFILES=$(circleci tests glob "tests/**/*.test.js" | \
                        circleci tests split --split-by=timings)
            npm test $TESTFILES
      - store_test_results:
          path: test-results
```### التوازي وتقسيم الاختبارات
```yaml
jobs:
  small-job:
    docker:
      - image: cimg/base:stable
    resource_class: small  # 1 vCPU, 2GB RAM
  
  large-job:
    docker:
      - image: cimg/base:stable
    resource_class: large  # 4 vCPU, 8GB RAM
  
  xlarge-job:
    docker:
      - image: cimg/base:stable
    resource_class: xlarge  # 8 vCPU, 16GB RAM
```### فئات الموارد
```yaml
version: 2.1

orbs:
  node: circleci/node@5.1.0

jobs:
  build:
    executor: node/default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Build Application
          command: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist
            - node_modules

  test:
    executor: node/default
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run:
          name: Run Unit Tests
          command: npm test
      - store_test_results:
          path: test-results

  deploy-staging:
    executor: node/default
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Deploy to Staging
          command: npm run deploy:staging

workflows:
  build-test-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy-staging:
          requires:
            - test
          filters:
            branches:
              only: develop
```## حالات الاستخدام الشائعة

### حالة الاستخدام 1: أنبوب تطبيق Node.js متعدد المراحل
```yaml
version: 2.1

orbs:
  docker: circleci/docker@2.2.0

jobs:
  build-and-push:
    executor: docker/docker
    steps:
      - setup_remote_docker:
          docker_layer_caching: true
      - checkout
      - docker/check
      - docker/build:
          image: myorg/myapp
          tag: ${CIRCLE_SHA1},latest
      - docker/push:
          image: myorg/myapp
          tag: ${CIRCLE_SHA1},latest

workflows:
  build-deploy:
    jobs:
      - build-and-push:
          context: docker-hub-creds
          filters:
            branches:
              only: main
```### حالة الاستخدام 2: إنشاء ودفع صورة Docker
```yaml
version: 2.1

jobs:
  test:
    docker:
      - image: cimg/python:3.11
    parallelism: 8
    steps:
      - checkout
      - run: pip install -r requirements.txt
      - run:
          name: Run Tests in Parallel
          command: |
            TESTFILES=$(circleci tests glob "tests/**/test_*.py" | \
                        circleci tests split --split-by=timings)
            pytest $TESTFILES \
              --junitxml=test-results/junit.xml \
              --cov=app \
              --cov-report=html
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: htmlcov

workflows:
  test:
    jobs:
      - test
```### حالة الاستخدام 3: اختبار متوازٍ مع تقسيم الاختبارات
```yaml
version: 2.1

parameters:
  run-integration-tests:
    type: boolean
    default: false
  deployment-environment:
    type: string
    default: "staging"

jobs:
  unit-test:
    docker:
      - image: cimg/node:18.16
    steps:
      - checkout
      - run: npm ci
      - run: npm run test:unit

  integration-test:
    docker:
      - image: cimg/node:18.16
    steps:
      - checkout
      - run: npm ci
      - run: npm run test:integration

  deploy:
    docker:
      - image: cimg/node:18.16
    parameters:
      environment:
        type: string
    steps:
      - checkout
      - run: npm ci
      - run: npm run deploy:<< parameters.environment >>

workflows:
  test-and-deploy:
    jobs:
      - unit-test
      - integration-test:
          when: << pipeline.parameters.run-integration-tests >>
      - deploy:
          environment: << pipeline.parameters.deployment-environment >>
          requires:
            - unit-test
          filters:
            branches:
              only: main
```### حالة الاستخدام 4: سير عمل شرطي مع معلمات
```yaml
version: 2.1

setup: true

orbs:
  path-filtering: circleci/path-filtering@0.1.3

workflows:
  setup-workflow:
    jobs:
      - path-filtering/filter:
          base-revision: main
          config-path: .circleci/continue-config.yml
          mapping: |
            services/api/.* api-build true
            services/web/.* web-build true
            packages/.* all-build true
```### حالة الاستخدام 5: Monorepo مع تصفية المسار
```yaml
version: 2.1

parameters:
  api-build:
    type: boolean
    default: false
  web-build:
    type: boolean
    default: false
  all-build:
    type: boolean
    default: false

jobs:
  build-api:
    docker:
      - image: cimg/node:18.16
    steps:
      - checkout
      - run: cd services/api && npm ci && npm run build

  build-web:
    docker:
      - image: cimg/node:18.16
    steps:
      - checkout
      - run: cd services/web && npm ci && npm run build

workflows:
  api-workflow:
    when: << pipeline.parameters.api-build >>
    jobs:
      - build-api

  web-workflow:
    when: << pipeline.parameters.web-build >>
    jobs:
      - build-web
```**continue-config.yml:**
`{{ checksum "package-lock.json" }}`## أفضل الممارسات

- **استخدام Orbs للمهام الشائعة**: استفد من orbs الخاصة بـ CircleCI للتكاملات القياسية (AWS، Docker، Slack) لتقليل تعقيد الإعدادات وعبء الصيانة.

- **تنفيذ التخزين المؤقت بشكل استراتيجي**: قم بتخزين التبعيات مؤقتًا باستخدام مفاتيح مبنية على المجموع التراكمي (
`{{ checksum "package.json" }}`) لتسريع عمليات البناء مع ضمان إلغاء صلاحية التخزين المؤقت عند تغير التبعيات.

- **تحسين فئات الموارد**: اختر فئات الموارد المناسبة لكل مهمة؛ استخدم حالات أصغر للمهام البسيطة واحتفظ بالحالات الأكبر للعمليات كثيفة الحوسبة مثل التجميع أو الاختبارات المعقدة.

- **تمكين Docker Layer Caching**: بالنسبة للمهام التي تبني صور Docker، قم بتمكين التخزين المؤقت لطبقات Docker.`docker_layer_caching: true`للتقليل بشكل كبير من أوقات البناء من خلال إعادة استخدام الطبقات غير المتغيرة.
`circleci tests split`**تقسيم الاختبارات للتنفيذ المتوازي**: استخدم
`--split-by=timings`لتوزيع الاختبارات عبر حاويات متوازية بناءً على أوقات التنفيذ التاريخية، مما يعظم الكفاءة.
`persist_to_workspace`للحفاظ على مخرجات البناء واستخدامها
`attach_workspace`بدلاً من إعادة البناء في الوظائف اللاحقة، مما يوفر الوقت ويضمن الاتساق.
`circleci config validate`**تطبيق مرشحات سير العمل**: استخدم مرشحات الفروع والعلامات للتحكم في وقت تشغيل الوظائف، ومنع عمليات النشر غير الضرورية والحفاظ على الاعتمادات مع ضمان الأمان.
`circleci local execute`**تخزين الأسرار في السياقات**: إدارة بيانات الاعتماد الحساسة في سياقات CircleCI بدلاً من متغيرات البيئة للمشروع لتحسين الأمان والتحكم في الوصول وإمكانية إعادة الاستخدام عبر المشاريع.

| مشكلة | حل |
|-------|----------|
| **"Config file not found" error** | Ensure `.circleci/config.yml` exists in repository root. Run `circleci config validate` to check file location and syntax. |
| **Local execution fails with Docker errors** | Verify Docker is running: `docker ps`. Ensure the CLI has access to Docker socket. On Linux, add user to docker group: `sudo usermod -aG docker $USER`. |
| **"Invalid configuration" during validation** | Run `circleci config process .circleci/config.yml` to see expanded config and identify syntax errors. Check YAML indentation (use spaces, not tabs). |
| **Jobs not triggering on push** | Verify project is followed: `circleci follow github/org/repo`. Check workflow filters aren't excluding your branch. Ensure webhook is configured in VCS settings. |
| **Workspace attachment fails** | Ensure `persist_to_workspace` in upstream job completes successfully. Verify `root` and `paths` match between persist and attach. Check job dependencies in workflow. |
| **Cache not restoring** | Verify cache key matches between `save_cache` and `restore_cache`. Use fallback keys: `keys: [v1-{{ checksum "file" }}, v1-]`. Check cache hasn't expired (30 days). |
| **Authentication errors with CLI** | Re-run `circleci setup` with a valid API token. Generate new token at `https://app.circleci.com/settings/user/tokens`. Verify token has correct permissions. |
| **Parallel test splitting not working** | Ensure test results are stored with `store_test_results`. Use glob patterns that match your test files. Verify `parallelism` is set greater than 1. |
| **Out of memory errors** | Increase `resource_class` to `large` or `xlarge`. Optimize memory-intensive operations. Check for memory leaks in application code. |
| **Context environment variables not available** | Verify job uses correct context in workflow: `context: context-name`. Check user has access to context in organization settings. Ensure variable names don't conflict. |
| **Orb import fails** | Verify orb exists: `circleci orb info namespace/orb@version`. Check version is valid. For private orbs, ensure organization has access and use `--org-id` flag. |**التحقق من التكوين محليًا**: قم دائمًا بتشغيل
`- run: circleci-agent step halt`واختبار الوظائف محليًا مع