آشنایی با Native Git در Postman

Native Git یا تجربه Git-connected فقط در برنامه دسکتاپ Postman در دسترس است. اگر گزینه اتصال به Git repository را نمی‌بینید، احتمالا در نسخه وب هستید و باید از Postman desktop app استفاده کنید.

با Native Git، تغییرات API در کنار کد و داخل Git انجام می‌شود و تا وقتی API به وضعیت پایدار و قابل انتشار نرسیده، به صورت عمدی با Postman Cloud همگام نمی‌شود. این کار کمک می‌کند تغییرات collection، environment، specification، SDK، mock و flow همراه با کد version control شود.

Local View و Cloud View

• Local View: نمای فایل‌هایی است که در Git repository محلی شما ذخیره شده‌اند. این نمای قابل ویرایش است و تغییرات اصلی API در همین‌جا انجام می‌شود.
• Cloud View: نمای داده‌های ذخیره‌شده روی Postman Cloud است. بهتر است این نما منبع خواندنی و پایدار برای تیم‌هایی باشد که به نسخه deploy شده API نیاز دارند.

در Local View می‌توانید collection را داخل Postman یا مستقیم در IDE ویرایش کنید. جریان پیشنهادی توسعه این است: Local View → Git → sync خودکار در CI → Cloud View.

مزایای Native Git

توسعه‌دهنده می‌تواند برای یک feature مثل اضافه کردن endpoint جدید یا تغییر پیاده‌سازی، branch جدا بسازد. وقتی feature آماده شد، pull request می‌تواند هم تغییرات کد و هم تغییرات collection را کنار هم داشته باشد. همچنین می‌توانید با Postman CLI تست‌ها را در CI/CD اجرا کنید.

راه‌اندازی workspace با Native Git

برای repoهایی که فقط یک service دارند، workspace را به root folder همان repo وصل کنید تا هم کد API و هم collectionها کنار هم باشند. برای mono-repoهایی که چند service دارند، بهتر است هر پوشه service را به workspace جدا وصل کنید، نه کل repo را به یک workspace واحد.

Sync با Postman Cloud

اگرچه توسعه‌دهنده‌ها معمولا در Local View کار می‌کنند، Cloud View برای همکاری با اعضایی مثل frontend developerها مهم است؛ کسانی که شاید repo را clone نکرده باشند. همه افراد پروژه باید در یک Postman team و workspace باشند. Personal workspace برای workflowهای Native Git مناسب نیست.

مقادیر local environment را در خود برنامه Postman نگه دارید و فقط مقدارهای Shared را به Git commit کنید. secretهای حساس را داخل Git repository ذخیره نکنید.

Push و Pull در Postman

برای push کردن تغییرات به Cloud، ابتدا در Local View تغییرات را بررسی کنید، سپس در footer روی Push to Postman Cloud کلیک کنید، itemهای مورد نظر را انتخاب کنید و روی Push to Cloud بزنید.

برای pull کردن از Cloud، به Cloud View بروید، روی Pull from Postman Cloud کلیک کنید، itemهای مورد نظر را انتخاب کنید و روی Pull from Cloud بزنید.

اتصال پروژه Git به workspace

1. workspace پروژه را باز کنید.
2. از sidebar روی Files کلیک کنید.
3. روی Open Folder کلیک کنید.
4. پروژه Git محلی را انتخاب کنید.
5. روی Connect کلیک کنید.

هر workspace فقط می‌تواند هم‌زمان به یک پوشه در فایل‌سیستم وصل باشد. برای استفاده از همان فایل‌ها در workspace دیگر، باید از workspace قبلی disconnect کنید.

بعد از اتصال، Postman به صورت خودکار دو پوشه می‌سازد: .postman که hidden است و postman که شامل زیرپوشه‌های collectionها و environmentها می‌شود.

اضافه کردن workflow برای انتشار در Postman Cloud

برای جلوگیری از خطای دستی و قدیمی شدن collectionهای cloud، بهتر است sync را در CI/CD خودکار کنید. ابتدا یک Postman API key بسازید و آن را به عنوان secret مثل POSTMAN_API_KEY در repository ذخیره کنید. سپس از دستور postman workspace push -y در pipeline استفاده کنید.

name: Publish changes to Postman
on:
  push:
    branches:
      - main

jobs:
  publish-changes:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Postman CLI
        run: |
          curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
      - name: Verify Postman CLI version
        run: postman --version
      - name: Login to Postman
        run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
      - name: Publish changes to Cloud
        run: postman workspace push -y

بهترین نکات برای CI/CD

• در محیط CI از گزینه -y یا --yes استفاده کنید تا promptهای تأیید دستی رد شوند.
• در mono-repoها از flagهایی مثل --collections-dir و --environments-dir برای مسیرهای هر service استفاده کنید.
• دستور push مرحله prepare را برای اعتبارسنجی فایل‌ها انجام می‌دهد. رد کردن آن با --no-prepare برای pipeline تولیدی پیشنهاد نمی‌شود.

توسعه با Native Git

برای کار روزانه، workspace متصل به service را باز کنید، به Local View بروید، branch جدید بسازید، تغییرات API را در Postman یا فایل‌های YAML انجام دهید، سپس فایل‌های تغییرکرده را commit و push کنید. بعد از merge و release، workflow انتشار اجرا می‌شود و Cloud View به‌روز می‌شود. تغییراتی که مستقیم در Cloud View انجام شوند، در push بعدی ممکن است با فایل‌های local جایگزین شوند.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.