# اسکریپت‌نویسی و CI/CD

CLI در اسکریپت همان‌طور کار می‌کند که در ترمینال. کلید API را با متغیرهای محیطی به آن بدهید، پاسخ‌هایش را به‌صورت JSON بخوانید، و بگذارید کد خروجش به اسکریپت بگوید چه اتفاقی افتاد. این صفحه هر کدام از این‌ها را نشان می‌دهد، همراه با خط لوله‌های کامل برای GitHub Actions، GitLab CI و Docker.

:::cards
- [کلید API یک اسکریپت را به آن بدهید](#کلید-api-یک-اسکریپت-را-به-آن-بدهید): دو متغیر محیطی، بدون زمینهٔ ذخیره‌شده.
- [کدهای خروج](#کدهای-خروج): ۰ وقتی کار کرد، و چرا کار نکرد.
- [خواندن پاسخ‌ها با jq](#خواندن-پاسخها-با-jq): شناسه‌ها، عنوان‌ها و تاریخ‌ها از دل JSON.
- [نمونه‌های خط لوله](#نمونههای-خط-لوله): GitHub Actions، GitLab CI و Docker.
:::

## اسکریپت چگونه از CLI استفاده می‌کند

یک استقرار می‌تواند اول از Status200 بپرسد که آیا حادثه‌ای باز است، و اگر هست متوقف شود:

```mermaid title="استقراری که تا باز بودن یک حادثه صبر می‌کند"
flowchart TB
    J["جاب CI آغاز می‌شود"] --> S["رازهایش تنظیم می‌کنند:<br/>STATUS200_API_KEY<br/>و STATUS200_URL"]
    S --> Q["status200 incident count<br/>برای حادثه‌های حل‌نشده"]
    Q -->|"۰"| D["استقرار"]
    Q -->|"۱ یا بیشتر"| X["توقف: یک حادثه<br/>باز است"]
    Q -->|"کد خروج ۲"| A["توقف: کلید API<br/>را بررسی کنید"]
```

## کلید API یک اسکریپت را به آن بدهید

`STATUS200_API_KEY` و `STATUS200_URL` را از رازهای سیستم CI خود تنظیم کنید. آن‌گاه CLI نه به `login` نیاز دارد و نه به فایل پیکربندی. برای یک دستور، پرچم همچنان بر آن‌ها مقدم است، و آن‌ها بر زمینه‌های ذخیره‌شده مقدم‌اند.

```bash
export STATUS200_API_KEY="$CI_STATUS200_API_KEY"
export STATUS200_URL="https://status200.ru"
status200 incident count
```

> [!TIP]
> به هر خط لوله کلید API خودش را بدهید، فقط با دسترسی‌ای که نیاز دارد: بررسی‌ای که فقط می‌خواند به کلیدی نیاز دارد که فقط می‌خواند. وقتی خط لوله کنار گذاشته شد، کلید را در Status200 حذف کنید.

اگر یک ماشین جاب‌های چند پروژه را اجرا می‌کند، برای هر پروژه یک زمینه ذخیره کنید و در هر دستور نامش را بیاورید، تا هیچ جابی هرگز زمینهٔ فعلی جاب دیگری را به کار نبرد:

```bash
status200 --context production incident count
status200 --context staging monitor count
```

## کدهای خروج

| کد | معنا | نمونه |
| --- | --- | --- |
| `0` | کار کرد | یک list، حتی اگر چیزی پیدا نکند |
| `1` | شکست خورد | Status200 درخواست را رد کرد، مانند `API error (422)`؛ JSON نامعتبر؛ گزینه‌ای جاافتاده یا ناشناخته؛ زمینه‌ای که ذخیره نشده است |
| `2` | کلید API قابل‌استفاده‌ای نیست | اعتبارنامه‌ای پیدا نشد؛ کلید API نامعتبر؛ کلیدی پایین‌تر از طرحش (`402`)؛ `401` |
| `3` | پیدا نشد | Status200 پاسخ `404` داد: رکورد وجود ندارد، در پروژهٔ دیگری است، یا کلید نمی‌تواند آن را بخواند |

`whoami` و `context current` حتی وقتی چیزی ذخیره نشده با `0` خارج می‌شوند: آنچه را تنظیم شده گزارش می‌کنند و آن را بررسی نمی‌کنند. اسکریپت حالت‌ها را با کد از هم جدا می‌کند:

```bash
status200 incident get "$INCIDENT_ID" -o json > incident.json
case $? in
  0) echo "Saved the incident to incident.json" ;;
  2) echo "Check STATUS200_API_KEY and STATUS200_URL" >&2; exit 1 ;;
  3) echo "There is no incident $INCIDENT_ID" >&2; exit 1 ;;
  *) echo "Status200 refused the request" >&2; exit 1 ;;
esac
```

پیام‌های خطا به خطای استاندارد می‌روند، پس `incident.json` فقط پاسخ را در خود دارد.

## خواندن پاسخ‌ها با jq

در اسکریپت‌ها `-o json` را بنویسید. CLI در پایپ به هر حال JSON چاپ می‌کند، اما این پرچم اسکریپت را هر جا که اجرا شود کارا نگه می‌دارد:

```bash
# The title of each incident
status200 incident list -o json | jq -r '.[].title'

# The ID of a new monitor
MONITOR_ID=$(status200 monitor create --data '{"name":"Checkout API","monitorType":"Manual"}' -o json | jq -r '._id')

# When each incident was created: dates come as objects
status200 incident list -o json | jq -r '.[] | "\(.createdAt.value)  \(.title)"'

# The newest 100 incidents as CSV
status200 incident list --limit 100 -o json | jq -r '.[] | [._id, .title, .createdAt.value] | @csv'
```

شمارش یک عدد چاپ می‌کند، آمادهٔ مقایسه:

```bash
OPEN=$(status200 incident count --query '{"currentIncidentState":{"isResolvedState":false}}')
echo "$OPEN incidents are open"
```

## ساختن رکوردها از فایل‌ها

رکوردها را به‌صورت فایل‌های JSON کنار کدتان نگه دارید و از همان‌جا بسازیدشان:

```json title="monitors/checkout-api.json"
{
  "name": "Checkout API",
  "monitorType": "Manual"
}
```

```bash
status200 monitor create --file monitors/checkout-api.json
```

چند رکورد از یک آرایهٔ JSON، برای هر کدام یک create:

```bash
jq -c '.[]' monitors.json | while IFS= read -r monitor; do
  status200 monitor create --data "$monitor" -o json | jq -r '._id'
done
```

> [!NOTE]
> هر اجرا رکوردهای تازه می‌سازد. برای هماهنگ نگه داشتن مانیتورها و صفحه‌های وضعیت با فایل‌ها، که فقط آنچه تغییر کرده را تغییر دهد و آنچه رفته را حذف کند، از [ارائه‌دهندهٔ Terraform](/docs/terraform/index) استفاده کنید.

## نمونه‌های خط لوله

:::tabs
@tab GitHub Actions
```yaml title=".github/workflows/deploy.yml"
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Install the Status200 CLI
        run: npm install -g @status200/cli
      - name: Stop while an incident is open
        env:
          STATUS200_API_KEY: ${{ secrets.STATUS200_API_KEY }}
          STATUS200_URL: https://status200.ru
        run: |
          OPEN=$(status200 incident count --query '{"currentIncidentState":{"isResolvedState":false}}')
          if [ "$OPEN" -gt 0 ]; then
            echo "$OPEN incidents are open: not deploying."
            exit 1
          fi
      - name: Deploy
        run: ./deploy.sh
```
@tab GitLab CI
```yaml title=".gitlab-ci.yml"
check-incidents:
  stage: test
  image: node:lts
  variables:
    STATUS200_URL: https://status200.ru
  script:
    - npm install -g @status200/cli
    - OPEN=$(status200 incident count --query '{"currentIncidentState":{"isResolvedState":false}}')
    - echo "$OPEN incidents are open"
    - test "$OPEN" -eq 0
```
@tab Docker
```dockerfile title="Dockerfile"
FROM node:lts-slim
RUN npm install -g @status200/cli
ENTRYPOINT ["status200"]
```
:::

در GitHub Actions، `STATUS200_API_KEY` را زیر **Settings → Secrets and variables → Actions** در مخزن اضافه کنید؛ در GitLab، آن را به‌عنوان یک متغیر CI/CD پوشیده (masked) اضافه کنید. با ایمیج Docker، متغیرها را به هر اجرا بدهید:

```bash
docker build -t status200-cli .
docker run --rm -e STATUS200_API_KEY -e STATUS200_URL status200-cli incident count
```

## گام‌های بعدی

:::cards
- [احراز هویت](/docs/cli/authentication): وقتی چند کلید تنظیم شده باشد، دستور کدام را به کار می‌برد.
- [قالب‌های خروجی](/docs/cli/output-formats): JSONی که اسکریپت‌هایتان می‌خوانند.
- [عملیات روی منابع](/docs/cli/resource-operations): فیلترها، صفحه‌بندی و فیلدهای یک رکورد.
- [ارائه‌دهندهٔ Terraform](/docs/terraform/index): پیکربندی Status200 را در فایل‌ها نگه دارید.
:::