GitHub Actions: توليد كتاب تفاعلي تلقائياً مع كل إصدار

إذا كانت مستنداتك أو ملاحظات الإصدار أو كتالوج منتجاتك موجودة كملف PDF داخل مستودعك، فلا داعي لنشر الكتاب التفاعلي يدوياً. مع GitHub Actions وواجهة FlipLink عبر سطر الأوامر، يمكنك في كل مرة تطلق فيها إصداراً أن تبني ملف الـ PDF، وتحوّله إلى كتاب تفاعلي منشور، وتعيد الرابط المباشر مباشرةً إلى الإصدار — وكل ذلك دون لمس لوحة التحكم.

هذه هي النسخة المخصّصة لبيئة GitHub من نشر الكتب التفاعلية عبر CI/CD. وإذا كنت تستخدم مشغّلاً آخر (GitLab CI أو CircleCI أو خادم cron)، فالخطوات تنطبق بسلاسة — ولا يتغيّر سوى شكل ملف الـ YAML.

ما الذي سنبنيه

سير عمل يُفعَّل عند نشر إصدار، ويقوم بالتالي:

1. يسحب نسخة من المستودع ويبني (أو يحدّد موقع) ملف الـ PDF الذي تريد نشره.
2. يثبّت واجهة FlipLink عبر سطر الأوامر.
3. ينشئ كتاباً تفاعلياً من ذلك الـ PDF وينشره، مع المصادقة بمفتاح API محفوظ كسرّ في المستودع.
4. يلتقط الرابط المباشر للكتاب التفاعلي من مخرجات JSON.
5. يعيد نشر هذا الرابط على الإصدار ليصل إلى فريقك على الفور.

إنه مثال نموذجي على الأتمتة: يقع حدث، فيُشغَّل سكربت، فيُشحن ناتج.

الخطوة 1 — احفظ مفتاح API كسرّ في المستودع

لا تلصق مفتاح API أبداً داخل ملف سير العمل. فملفات سير العمل تعيش داخل مستودعك — وأي شخص لديه صلاحية القراءة (وكل نسخة منسوخة) يمكنه رؤيتها. استخدم سرّاً مشفّراً بدلاً من ذلك:

1. سجّل الدخول على https://go.fliplink.me، وافتح صفحة Subscription، وانسخ مفتاح API الخاص بك.
2. في مستودعك على GitHub، اذهب إلى Settings → Secrets and variables → Actions.
3. اضغط على New repository secret.
4. سمِّه FLIPLINK_API_KEY، والصق المفتاح كقيمة له.
5. اضغط على Add secret.

يقرأ سير العمل المفتاح عبر secrets.FLIPLINK_API_KEY ويمرّره إلى الـ CLI كمتغيّر بيئة باسم FLIPLINK_API_KEY. وتتحقق الواجهة من متغيّر البيئة هذا تلقائياً، لذا لا حاجة لخطوة config set-key في بيئة الـ CI.

الخطوة 2 — ملف سير العمل

أنشئ الملف .github/workflows/publish-flipbook.yml:

name: Publish flipbook on release

on:
  release:
    types: [published]

permissions:
  contents: write   # needed to edit the release notes in the last step

jobs:
  flipbook:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      # Replace this with however you produce the PDF.
      # If the PDF is committed in the repo, you can delete this step.
      - name: Build the PDF
        run: |
          mkdir -p dist
          # e.g. your doc tooling outputs dist/release-notes.pdf
          ls -lh dist/release-notes.pdf

      - name: Install FlipLink CLI
        run: npm install -g fliplink-cli

      - name: Create and publish flipbook
        id: flipbook
        env:
          FLIPLINK_API_KEY: ${{ secrets.FLIPLINK_API_KEY }}
        run: |
          ID=$(fliplink flipbook create ./dist/release-notes.pdf \
            --title "Release ${{ github.event.release.tag_name }}" \
            --name "release-${{ github.event.release.tag_name }}" \
            --json | jq -r '.ID')

          fliplink flipbook publish "$ID"

          URL=$(fliplink flipbook share-link "$ID" --json | jq -r '.URL')

          echo "id=$ID" >> "$GITHUB_OUTPUT"
          echo "url=$URL" >> "$GITHUB_OUTPUT"
          echo "Published flipbook: $URL"

      - name: Comment the URL on the release
        uses: actions/github-script@v7
        with:
          script: |
            const url = "${{ steps.flipbook.outputs.url }}";
            const release = context.payload.release;
            await github.rest.repos.updateRelease({
              owner: context.repo.owner,
              repo: context.repo.repo,
              release_id: release.id,
              body: `${release.body || ""}\n\nFlipbook published: ${url}`
            });

بعض الملاحظات حول خطوة الإنشاء:

• يرفع الأمر fliplink flipbook create ./path.pdf ملف الـ PDF ويُرجع الكتاب التفاعلي الجديد. ومع --json تحصل على الاستجابة الخام، ويستخرج jq -r '.ID' المعرّف منها.
• يطلق الأمر fliplink flipbook publish "$ID" الكتاب التفاعلي مباشرةً. (إنشاء كتاب تفاعلي لا ينشره — فالنشر خطوة منفصلة وصريحة.)
• يُرجع الأمر fliplink flipbook share-link "$ID" رابط العارض العام، الذي نلتقطه بالطريقة ذاتها عبر jq.
• نكتب القيمتين id وurl إلى $GITHUB_OUTPUT لتتمكّن الخطوات اللاحقة من الإشارة إليهما عبر steps.flipbook.outputs.url.

كل ما هنا يستخدم أوامر CLI موثّقة فقط والعَلَم --json. وإذا احتجت إجراءً لا تغطّيه الواجهة، فانتقل إلى المنفذ الخلفي fliplink api — راجع توثيق الـ CLI للاطلاع على الواجهة كاملةً، أو مرجع الـ API لكل نقطة وصول.

🚀

جرّب FlipLink مجاناً

حوّل ملف PDF خلال ثوانٍ. لا تسجيل ولا بطاقة ائتمان — ارفع ملفك وانطلق.

Drop your PDF here or click to browse

الحجم الأقصى 40MB

الباقات المدفوعة من $39 ترفع هذا الحد إلى 150 MB.

الخطوة 3 — إعادة نشر الرابط

أنظف طريقة لإبراز الرابط هي نشره على الإصدار نفسه. وخطوة actions/github-script أعلاه تفعل ذلك. وإذا كنت تفضّل واجهة GitHub عبر سطر الأوامر (gh مثبّت مسبقاً على مشغّلات GitHub المستضافة)، فإن هذا السطر الواحد يعمل أيضاً:

      - name: Comment via gh
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release view "${{ github.event.release.tag_name }}" \
            --json body --jq '.body' > old-body.txt
          printf '\n\nFlipbook: %s\n' "${{ steps.flipbook.outputs.url }}" >> old-body.txt
          gh release edit "${{ github.event.release.tag_name }}" \
            --notes-file old-body.txt

يُلحق ذلك رابط الكتاب التفاعلي بملاحظات الإصدار، فيصبح ظاهراً تماماً حيث يقرأ الناس سجلّ التغييرات. اختر ما يناسب عادات فريقك — فكلاهما يقرأ الرابط من المصدر ذاته steps.flipbook.outputs.url.

ملاحظات حول التخزين المؤقت والأداء

بعض الأمور التي تُبقي سير العمل سريعاً وقابلاً للتنبؤ:

• خزّن npm مؤقتاً. أضف cache: npm إلى خطوة setup-node إذا كان مستودعك يحتوي على ملف قفل — فهذا يسرّع تثبيت الـ CLI وأي أدوات لمعالجة الـ PDF في عمليات التشغيل المتكررة.
• راقب حدّ المعدّل. تسمح واجهة FlipLink بـ 300 طلب في الدقيقة لكل مفتاح. الإصدار الواحد ينشر كتاباً تفاعلياً واحداً، فأنت بعيد كل البعد عن السقف — لكن إذا وزّعت العمل على ملفات PDF كثيرة في مهمة واحدة، فباعِد بين الطلبات.
• تفرّع عند الفشل. ينهي الـ CLI عمله بالرمز 0 عند النجاح، و1 عند خطأ في الطلب أو في HTTP، و2 عند خطأ في التطبيق. وبما أن كل أمر في كتلة run قد يفشل، تفشل الخطوة بوضوح إذا حدث أي خلل — وهو بالضبط ما تريده في بيئة الـ CI.
• اضبط المُحفِّز بدقّة. يعني types: [published] أن سير العمل يُشغَّل مرة واحدة، عندما تنشر إصداراً فعلاً — لا عند المسوّدات أو التعديلات قبل النشر. وهذا يتجنّب الكتب التفاعلية المكررة بالخطأ.

الخلاصة

بملف سير عمل واحد وسرّ واحد في المستودع، أصبح كل إصدار الآن يشحن كتاباً تفاعلياً منشوراً ويعيد نشر الرابط إلى فريقك — بلا أي خطوات يدوية. ومن هنا يمكنك تحويل مجلد كامل دفعةً واحدة، أو كتابة سكربتات لأنابيب أكثر ثراءً باستخدام jq، أو نقل المنطق إلى وكيل ذكاء اصطناعي. وكل هذه الأنماط تبنى على الـ CLI ذاته.

قراءات ذات صلة

• البدء مع واجهة FlipLink عبر سطر الأوامر
• أتمتة نشر الكتب التفاعلية في أنبوب CI/CD لديك
• توثيق الـ CLI
• مرجع واجهة FlipLink للـ API
• ما هي الأتمتة؟ (مسرد المصطلحات)