CI/CD integratsiyasi

CI/CD integratsiyasi Enterprise rejasidagi foydalanuvchilar uchun mavjud.

CI/CD integratsiyasi nima uchun va qanday yordam berishini bilish uchun ushbu videoni ko'rishingiz mumkin:

Graph'larni publish qilish

Avval ilovaning bootstrap fayli (main.ts) ni GraphPublisher class'idan foydalanadigan qilib sozlaymiz (@nestjs/devtools-integration paketidan export qilinadi - batafsil ma'lumot uchun oldingi bobga qarang):

1async function bootstrap() {
2  const shouldPublishGraph = process.env.PUBLISH_GRAPH === "true";
3
4  const app = await NestFactory.create(AppModule, {
5    snapshot: true,
6    preview: shouldPublishGraph,
7  });
8
9  if (shouldPublishGraph) {
10    await app.init();
11
12    const publishOptions = { ... } // NOTE: this options object will vary depending on the CI/CD provider you're using
13    const graphPublisher = new GraphPublisher(app);
14    await graphPublisher.publish(publishOptions);
15
16    await app.close();
17  } else {
18    await app.listen(process.env.PORT ?? 3000);
19  }
20}

Ko'rib turganingizdek, bu yerda GraphPublisher serialized graph'ni markaziy registry'ga publish qilish uchun ishlatilmoqda. PUBLISH_GRAPH - graph publish qilinsinmi (CI/CD workflow), yoki yo'qmi (oddiy application bootstrap) degan qarorni boshqaruvchi custom environment variable. Bundan tashqari, bu yerda preview atributi ham true qilingan. Bu flag yoqilganda ilova preview mode'da bootstrap bo'ladi, ya'ni controller, enhancer va provider'larning constructor'lari hamda lifecycle hook'lari bajarilmaydi. Eslatma: bu majburiy emas, lekin jarayonni soddalashtiradi, chunki bunday holatda CI/CD pipeline ichida ilovani ishga tushirganda real database va boshqa tashqi tizimlarga ulanishingiz shart bo'lmaydi.

publishOptions obyekti qaysi CI/CD provider'dan foydalanayotganingizga qarab farq qiladi. Quyidagi bo'limlarda eng ommabop CI/CD provider'lar uchun yo'riqnomalarni ko'rsatamiz.

Graph muvaffaqiyatli publish qilingach, workflow oynasida quyidagiga o'xshash chiqishni ko'rasiz:

Graph har safar publish qilinganda, loyiha sahifasida yangi yozuv paydo bo'lishi kerak:

Hisobotlar

Devtools har bir build uchun hisobot yaratadi, ammo buning uchun markaziy registry'da mos snapshot allaqachon saqlangan bo'lishi kerak. Masalan, graph avvaldan publish qilingan master branch'ga qarshi PR ochsangiz, ilova farqlarni aniqlab hisobot yaratadi. Aks holda hisobot yaratilmaydi.

Hisobotlarni ko'rish uchun loyiha sahifasiga o'ting (organizations bo'limiga qarang).

Bu, ayniqsa, code review vaqtida ko'zdan chetda qolib ketishi mumkin bo'lgan o'zgarishlarni aniqlashda foydali. Masalan, kimdir chuqur joylashgan provider ning scope'ini o'zgartirdi deylik. Bunday o'zgarish reviewer'ga darhol sezilmasligi mumkin, ammo Devtools yordamida uni osongina ko'rib, bu ataylab qilinganini tekshirish mumkin. Yoki ma'lum bir endpoint'dan guard olib tashlansa, hisobotda bu affected sifatida ko'rinadi. Agar o'sha route uchun integration yoki e2e testlar bo'lmasa, endpoint himoyasiz qolganini o'z vaqtida sezmay qolishimiz mumkin.

Shuningdek, agar katta codebase ustida ishlayotgan bo'lsak va biror modulni global qilib yuborsak, graph'ga qancha edge qo'shilganini ko'ramiz. Ko'p holatlarda bu noto'g'ri yo'nalishda ketayotganimizni bildiradi.

Build preview

Har bir publish qilingan graph uchun vaqt bo'yicha orqaga qaytib, Preview tugmasi orqali uning oldingi holatini ko'rishimiz mumkin. Bundan tashqari, hisobot yaratilgan bo'lsa, graph ustidagi farqlar highlight qilingan bo'ladi:

• yashil node'lar qo'shilgan elementlarni bildiradi
• och oq node'lar yangilangan elementlarni bildiradi
• qizil node'lar o'chirilgan elementlarni bildiradi

Quyidagi skrinshotga qarang:

Orqaga qaytish imkoniyati joriy graph'ni oldingisi bilan solishtirib, muammoni tekshirish va troubleshooting qilishga yordam beradi. Sozlamalaringizga qarab, har bir pull request (hatto har bir commit ham) registry'da o'z snapshot'iga ega bo'lishi mumkin. Shu sabab orqaga qaytib, nimalar o'zgarganini osongina ko'rishingiz mumkin. Devtools'ni Git'ga o'xshatish mumkin, lekin u Nest ilovangiz graph'ini qanday qurishini tushunadi va uni vizualizatsiya ham qila oladi.

Integratsiyalar: GitHub Actions

Avval loyihangizdagi .github/workflows katalogida yangi GitHub workflow yarating va uni, masalan, publish-graph.yml deb nomlang. Fayl ichida quyidagi ta'rifdan foydalaning:

1name: Devtools
2
3on:
4  push:
5    branches:
6      - master
7  pull_request:
8    branches:
9      - '*'
10
11jobs:
12  publish:
13    if: github.actor!= 'dependabot[bot]'
14    name: Publish graph
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/checkout@v3
18      - uses: actions/setup-node@v3
19        with:
20          node-version: '16'
21          cache: 'npm'
22      - name: Install dependencies
23        run: npm ci
24      - name: Setup Environment (PR)
25        if: {{ '${{' }} github.event_name == 'pull_request' {{ '}}' }}
26        shell: bash
27        run: |
28          echo "COMMIT_SHA={{ '${{' }} github.event.pull_request.head.sha {{ '}}' }}" >>\${GITHUB_ENV}
29      - name: Setup Environment (Push)
30        if: {{ '${{' }} github.event_name == 'push' {{ '}}' }}
31        shell: bash
32        run: |
33          echo "COMMIT_SHA=\${GITHUB_SHA}" >> \${GITHUB_ENV}
34      - name: Publish
35        run: PUBLISH_GRAPH=true npm run start
36        env:
37          DEVTOOLS_API_KEY: CHANGE_THIS_TO_YOUR_API_KEY
38          REPOSITORY_NAME: {{ '${{' }} github.event.repository.name {{ '}}' }}
39          BRANCH_NAME: {{ '${{' }} github.head_ref || github.ref_name {{ '}}' }}
40          TARGET_SHA: {{ '${{' }} github.event.pull_request.base.sha {{ '}}' }}

Ideal holatda DEVTOOLS_API_KEY environment variable'i GitHub Secrets'dan olinishi kerak. Batafsil ma'lumot bu yerda.

Ushbu workflow master branch'ga qaragan har bir pull request uchun yoki master branch'ga to'g'ridan-to'g'ri commit bo'lganda ishga tushadi. Bu konfiguratsiyani loyiha ehtiyojiga qarab bemalol moslashingiz mumkin. Muhimi, GraphPublisher ishlashi uchun zarur environment variable'larni berishimiz kerak.

Biroq ushbu workflow'dan foydalanishni boshlashdan oldin bitta variable'ni yangilash kerak - DEVTOOLS_API_KEY. Loyihangiz uchun maxsus API key'ni ushbu sahifa orqali yaratishingiz mumkin.

Oxirida yana main.ts fayliga qaytib, oldin bo'sh qoldirgan publishOptions obyektini yangilang.

1const publishOptions = {
2  apiKey: process.env.DEVTOOLS_API_KEY,
3  repository: process.env.REPOSITORY_NAME,
4  owner: process.env.GITHUB_REPOSITORY_OWNER,
5  sha: process.env.COMMIT_SHA,
6  target: process.env.TARGET_SHA,
7  trigger: process.env.GITHUB_BASE_REF ? 'pull' : 'push',
8  branch: process.env.BRANCH_NAME,
9};

Eng yaxshi developer experience uchun loyihangizga GitHub application ni integratsiya qiling. Buning uchun "Integrate GitHub app" tugmasini bosing (quyidagi skrinshotga qarang). Eslatma: bu majburiy emas.

Ushbu integratsiya bilan preview/report yaratish jarayonining holatini bevosita pull request ichida ko'rasiz:

Integratsiyalar: GitLab Pipelines

Avval loyihangiz root katalogida yangi GitLab CI konfiguratsiya fayli yarating va uni, masalan, .gitlab-ci.yml deb nomlang. Fayl ichida quyidagi ta'rifdan foydalaning:

1const publishOptions = {
2  apiKey: process.env.DEVTOOLS_API_KEY,
3  repository: process.env.REPOSITORY_NAME,
4  owner: process.env.GITHUB_REPOSITORY_OWNER,
5  sha: process.env.COMMIT_SHA,
6  target: process.env.TARGET_SHA,
7  trigger: process.env.GITHUB_BASE_REF ? 'pull' : 'push',
8  branch: process.env.BRANCH_NAME,
9};

Ushbu workflow master branch'ga qaragan har bir pull request uchun yoki master branch'ga to'g'ridan-to'g'ri commit bo'lganda ishga tushadi. Uni loyiha ehtiyojiga qarab moslashtirishingiz mumkin. Muhimi, GraphPublisher ishlashi uchun zarur environment variable'larni uzatishdir.

Biroq ushbu workflow ta'rifida foydalanishni boshlashdan oldin yangilanishi kerak bo'lgan bitta variable bor - DEVTOOLS_API_KEY. Loyihangiz uchun maxsus API key'ni mos sahifadan yaratishingiz mumkin.

Oxirida yana main.ts fayliga qaytib, oldin bo'sh qoldirgan publishOptions obyektini yangilang.

1image: node:16
2
3stages:
4  - build
5
6cache:
7  key:
8    files:
9      - package-lock.json
10  paths:
11    - node_modules/
12
13workflow:
14  rules:
15    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
16      when: always
17    - if: $CI_COMMIT_BRANCH == "master" && $CI_PIPELINE_SOURCE == "push"
18      when: always
19    - when: never
20
21install_dependencies:
22  stage: build
23  script:
24    - npm ci
25
26publish_graph:
27  stage: build
28  needs:
29    - install_dependencies
30  script: npm run start
31  variables:
32    PUBLISH_GRAPH: 'true'
33    DEVTOOLS_API_KEY: 'CHANGE_THIS_TO_YOUR_API_KEY'

Boshqa CI/CD vositalari

Nest Devtools'ning CI/CD integratsiyasidan xohlagan CI/CD vositangiz bilan foydalanishingiz mumkin (masalan, Bitbucket Pipelines, CircleCI va boshqalar). Shu sabab yuqorida ko'rsatilgan provider'lar bilan cheklanib qolmang.

Muayyan commit/build/PR uchun graph publish qilishda qanday ma'lumot kerakligini tushunish uchun quyidagi publishOptions konfiguratsiyasiga qarang.

1const publishOptions = {
2  apiKey: process.env.DEVTOOLS_API_KEY,
3  repository: process.env.CI_PROJECT_NAME,
4  owner: process.env.CI_PROJECT_ROOT_NAMESPACE,
5  sha: process.env.CI_COMMIT_SHA,
6  target: process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA,
7  trigger: process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA ? 'pull' : 'push',
8  branch: process.env.CI_COMMIT_BRANCH ?? process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME,
9};

Bu ma'lumotlarning ko'p qismi CI/CD'ning built-in environment variable'lari orqali beriladi (qarang: CircleCI built-in environment list va Bitbucket variables).

Graph publish qiluvchi pipeline konfiguratsiyasi uchun quyidagi trigger'lardan foydalanishni tavsiya qilamiz:

• push eventi - faqat joriy branch deployment muhitini ifodalasa, masalan master, main, staging, production va hokazo.
• pull request eventi - har doim yoki target branch deployment muhitini ifodalaganda (yuqoriga qarang)