ورقة مرجعية لـ GitHub Actions

جميع الأدوات
مجاني

مرجع GitHub Actions قابل للبحث والطباعة — مشغّلات سير العمل والوظائف والخطوات والتعبيرات والمصفوفات والتخزين المؤقت وسير العمل القابل لإعادة الاستخدام. مجاني.

Workflow skeleton & triggers

12
.github/workflows/ci.yml
Where workflow files live
name: CI
Workflow display name
on: push
Run on every push
on: { push: { branches: [main] } }
Only pushes to main
on: { push: { tags: ["v*"] } }
Run on version tags
on: pull_request
Run on PR open/update
on: { pull_request: { paths: ["src/**"] } }
Only when paths change
on: { schedule: [{ cron: "0 6 * * 1" }] }
Cron: Mondays 06:00 UTC
on: workflow_dispatch
Manual "Run workflow" button
workflow_dispatch: { inputs: { env: { type: choice, options: [dev, prod] } } }
Manual run with inputs
on: { release: { types: [published] } }
Run when a release ships
on: workflow_call
Make workflow reusable

Jobs & runners

12
jobs: { build: { runs-on: ubuntu-latest } }
Define a job and its runner
runs-on: [macos-latest / windows-latest]
Other hosted runner images
runs-on: [self-hosted, linux, x64]
Route to self-hosted by labels
needs: build
Run after another job
needs: [lint, test]
Wait for several jobs
if: github.ref == 'refs/heads/main'
Conditional job
container: node:22
Run job inside a Docker image
services: { redis: { image: redis:7, ports: ["6379:6379"] } }
Sidecar service container
outputs: { sha: ${{ steps.vars.outputs.sha }} }
Expose job outputs
needs.build.outputs.sha
Read another job's output
defaults: { run: { working-directory: app } }
Default dir for run steps
strategy: { fail-fast: false }
Keep matrix jobs running

Steps & popular actions

14
- uses: actions/checkout@v4
Clone the repository
- uses: actions/checkout@v4 with fetch-depth: 0
Full history (tags, blame)
- uses: actions/setup-node@v4 with node-version: 22
Install Node.js
- uses: actions/setup-python@v5 with python-version: "3.12"
Install Python
- uses: shivammathur/setup-php@v2 with php-version: "8.3"
Install PHP
- run: npm ci && npm test
Run shell commands
- run: | (multiline)
Multi-line script step
- name: Build
Readable step name in logs
- id: vars
Reference step outputs later
echo "sha=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
Set a step output
echo "PATH_EXTRA=/opt/bin" >> "$GITHUB_ENV"
Set env for later steps
- uses: actions/upload-artifact@v4
Save build outputs
- uses: actions/download-artifact@v4
Fetch artifacts in later jobs
continue-on-error: true
Don't fail the job on error

Expressions & contexts

14
${{ github.ref }}
Full ref, e.g. refs/heads/main
${{ github.ref_name }}
Branch or tag name only
${{ github.sha }}
Commit SHA being built
${{ github.event_name }}
Trigger: push, pull_request...
${{ github.actor }}
User who triggered the run
${{ github.repository }}
owner/repo string
${{ github.event.pull_request.number }}
Dig into the event payload
${{ secrets.API_KEY }}
Encrypted repo/org secret
${{ vars.SITE_URL }}
Non-secret config variable
${{ env.NODE_ENV }}
Environment variable
${{ runner.os }} / ${{ runner.temp }}
Runner OS and temp dir
${{ steps.vars.outputs.sha }}
Output of an earlier step
contains(), startsWith(), format()
Expression helper functions
GITHUB_TOKEN
Auto-provided per-run token

Conditionals & matrix

11
if: success() / failure() / always()
Run based on prior status
if: cancelled()
Only when the run is cancelled
if: github.event_name == 'push'
Trigger-specific step
if: startsWith(github.ref, 'refs/tags/')
Only for tag builds
if: contains(github.event.head_commit.message, '[skip e2e]')
Commit-message switches
strategy: { matrix: { node: [20, 22] } }
One job per matrix value
matrix: { os: [ubuntu-latest, macos-latest], node: [20, 22] }
Cross-product matrix (4 jobs)
${{ matrix.node }}
Use the matrix value
matrix: { include: [{ os: ubuntu-latest, node: 23, experimental: true }] }
Add extra combos
matrix: { exclude: [{ os: macos-latest, node: 20 }] }
Drop combos
max-parallel: 2
Throttle concurrent matrix jobs

Caching & artifacts

11
- uses: actions/cache@v4
Generic dependency cache
key: npm-${{ hashFiles('package-lock.json') }}
Cache key from lockfile hash
restore-keys: | npm-
Fallback prefix on miss
path: ~/.npm
What directory to cache
setup-node@v4 with cache: npm
Built-in npm cache (easiest)
setup-python@v5 with cache: pip
Built-in pip cache
upload-artifact@v4 with name/path
Store files for download
upload-artifact: retention-days: 5
Auto-delete artifacts
download-artifact@v4 (no name)
Download all artifacts
if-no-files-found: error
Fail if the path is empty
Cache limit: 10 GB per repo
Old caches get evicted

Environments & permissions

11
permissions: { contents: read }
Least-privilege GITHUB_TOKEN
permissions: { contents: write, pull-requests: write }
Allow pushes + PR comments
permissions: { id-token: write }
OIDC for cloud auth (no keys)
environment: production
Use a deploy environment
environment: { name: prod, url: https://app.example.com }
Link shown on the run
Environment protection rules
Required reviewers, wait timer
env: { NODE_ENV: production }
Env at workflow/job/step level
secrets.GITHUB_TOKEN
Scoped to the current repo
Settings > Secrets and variables > Actions
Where to define secrets
Org secrets with repo allowlists
Share secrets across repos
pull_request_target — use with care
Runs with secrets on fork PRs

Reusable workflows & composite actions

11
on: { workflow_call: { inputs: ..., secrets: ... } }
Declare a reusable workflow
jobs: { ci: { uses: org/repo/.github/workflows/ci.yml@v1 } }
Call a reusable workflow
uses: ./.github/workflows/ci.yml
Call one from the same repo
with: { node-version: 22 }
Pass inputs to the callee
secrets: inherit
Forward all caller secrets
${{ inputs.node-version }}
Read inputs in the callee
action.yml with runs: { using: composite }
Define a composite action
steps: - run: ... shell: bash
Composite steps need shell:
uses: ./.github/actions/setup
Use a local composite action
inputs/outputs in action.yml
Action interface definition
Nesting limit: 4 levels of reusable calls
Plan the call depth

Concurrency & timeouts

9
concurrency: { group: deploy, cancel-in-progress: true }
Kill superseded runs
group: ${{ github.workflow }}-${{ github.ref }}
One run per branch
cancel-in-progress: false
Queue instead of cancel
timeout-minutes: 15 (job level)
Kill runaway jobs (default 360)
timeout-minutes: 5 (step level)
Cap a single step
retry via nick-fields/retry@v3
Retry flaky steps
jobs.<id>.strategy.max-parallel
Limit parallel matrix legs
if: always() on cleanup steps
Cleanup even after failure
Scheduled runs can be delayed/skipped
Cron is best-effort, not exact

Common recipes

12
on: push: tags: ["v*"] + softprops/action-gh-release@v2
Release on version tag
on: push: paths: ["apps/api/**"]
Monorepo: build only what changed
dorny/paths-filter@v3
Per-job change detection
peaceiris/actions-gh-pages@v4
Deploy static site to Pages
docker/build-push-action@v6
Build and push Docker images
docker/login-action@v3 with ghcr.io
Log in to GitHub registry
aws-actions/configure-aws-credentials@v4 (OIDC)
Keyless AWS deploys
appleboy/ssh-action@v1
Run commands on a server
codecov/codecov-action@v4
Upload coverage reports
github/codeql-action
Code scanning / security
dependabot.yml + auto-merge workflow
Auto-update dependencies
schedule + stale action
Auto-close stale issues

Debugging

12
Secret ACTIONS_STEP_DEBUG = true
Verbose step debug logs
Secret ACTIONS_RUNNER_DEBUG = true
Runner diagnostic logs
Re-run jobs > Enable debug logging
One-off debug re-run
act
Run workflows locally in Docker
act -j build
Run a single job locally
act -s GITHUB_TOKEN=$(gh auth token)
Pass secrets to act
echo "::debug::message"
Emit a debug log line
echo "::error file=app.js,line=1::Oops"
Annotate code with errors
echo "::group::Install" ... "::endgroup::"
Collapsible log sections
$GITHUB_STEP_SUMMARY
Write Markdown run summary
mxschmitt/action-tmate@v3
SSH into a live runner
cat "$GITHUB_EVENT_PATH"
Inspect the raw event JSON

gh CLI for Actions

13
gh run list
Recent workflow runs
gh run list --workflow ci.yml
Runs for one workflow
gh run watch
Live-follow the latest run
gh run view 123456 --log
Full logs of a run
gh run view --log-failed
Only the failed steps' logs
gh run rerun 123456 --failed
Re-run failed jobs only
gh run cancel 123456
Cancel a run
gh run download 123456
Download run artifacts
gh workflow list
List workflows in the repo
gh workflow run ci.yml -f env=prod
Trigger workflow_dispatch
gh workflow disable ci.yml
Disable a workflow
gh secret set API_KEY
Set a repo secret
gh cache list / gh cache delete
Inspect and prune caches

لا يوجد إدخال يطابق “:q”.

حول ورقة مرجعية لـ GitHub Actions

تضغط ورقة الغش هذه لـ GitHub Actions ملفات YAML لسير العمل في صفحة واحدة قابلة للبحث: هيكل سير العمل والمشغّلات، والمهام والمشغّلات (runners)، والخطوات والإجراءات الشائعة، والتعابير والسياقات، والشروط وبنى المصفوفة، والتخزين المؤقت والمخرجات، والبيئات والصلاحيات، وسير العمل القابل لإعادة الاستخدام والإجراءات المركّبة، والتزامن والمهل الزمنية، والوصفات الشائعة، والتصحيح، وأوامر gh CLI الخاصة بـ Actions.

ملفات سير العمل هي في معظمها بنية محفوظة — أي مشغّل يعمل عند وسم، وكيف تشير إلى سرّ، وتعبير if الذي يتخطى خطوة على فرع منسوخ (fork)، ونمط مفتاح التخزين المؤقت لملف قفل — لذا يعرض كل صف مقطع YAML مع شرح من سطر واحد.

الورقة مجانية وتعمل من جانب العميل: صفِّ الصفوف مباشرة عبر مربع البحث، وتنقّل بين الأقسام عبر جدول المحتويات الملتصق، وانسخ أي مقطع بنقرة واحدة، واطبع الصفحة كمرجع على مكتبك.

كيفية استخدام ورقة مرجعية لـ GitHub Actions

  1. تصفّح الأقسام سريعًا، من «هيكل سير العمل والمشغّلات» و«المهام والمشغّلات» إلى «gh CLI لـ Actions».
  2. ابحث عن كلمة مفتاحية مثل matrix أو secrets أو cache لتصفية كل صف مباشرة.
  3. انتقل إلى «الوصفات الشائعة» لمهمة بناء أو اختبار أو نشر جاهزة لتكييفها.
  4. انقر على مقطع YAML أو أيقونة النسخ الخاصة به لنسخه إلى ملف سير العمل لديك.
  5. اطبع الورقة للحصول على مرجع GitHub Actions يعمل دون اتصال.

الأسئلة الشائعة

اثنا عشر قسمًا: هيكل سير العمل والمشغّلات، والمهام والمشغّلات، والخطوات والإجراءات الشائعة، والتعابير والسياقات، والشروط والمصفوفة، والتخزين المؤقت والمخرجات، والبيئات والصلاحيات، وسير العمل القابل لإعادة الاستخدام والمركّب، والتزامن والمهل الزمنية، والوصفات الشائعة، والتصحيح، وgh CLI.

نعم — push وpull_request وschedule مع cron وworkflow_dispatch مع المدخلات وrelease ومرشّحات المسار والفرع التي تضيّق نطاق كلٍّ منها.

لكليهما قسمه الخاص: استراتيجيات المصفوفة مع include وexclude وfail-fast، وactions/cache مع مفاتيح مبنية على ملف القفل وrestore-keys.

نعم. انقر على أي صف أو على أيقونة النسخ الخاصة به وسيصل المقطع إلى حافظتك مع تأكيد موجز.

نعم، مجاني تمامًا — قابل للبحث والطباعة ويُعرض في متصفحك دون تسجيل.
شارك هذا
أدوات ذات صلة
ورقة Git المرجعية مرجع Git قابل للبحث والطباعة — الإعداد، الفروع، الدمج، إعادة الأساس، المستودعات البعيدة، التخزين المؤقت، الوسوم والتراجع عن التغييرات. مجانًا. مجاني
ورقة Docker المرجعية مرجع Docker قابل للبحث والطباعة — الصور، الحاويات، خيارات التشغيل، Dockerfile، وحدات التخزين، الشبكات، Compose والتنظيف. مجانًا. مجاني
ورقة مرجعية لـ Kubernetes / kubectl مرجع kubectl قابل للبحث والطباعة — السياقات والحاويات (pods) وعمليات النشر والخدمات والإعدادات والأسرار والتوسيع واستكشاف الأخطاء. مجاني. مجاني
ورقة JavaScript المرجعية مرجع قابل للبحث والطباعة لـ JavaScript الحديثة — البنية والمصفوفات والسلاسل والكائنات وasync/await وDOM وميزات ES2022+. مجاني. مجاني
ورقة PHP المرجعية مرجع PHP 8.3+ قابل للبحث والطباعة — البنية والسلاسل والمصفوفات والدوال والأصناف والتعدادات والخصائص والميزات الحديثة. مجاني. مجاني
ورقة MySQL المرجعية مرجع MySQL قابل للبحث والطباعة — الاستعلامات والوصلات والفهارس والدوال وأنواع البيانات وأوامر الإدارة. مجاني. مجاني
عمليات البحث الشائعة
github actions cheat sheet بنية workflow في github actions مثال github actions yaml github actions matrix build github actions cache قائمة مشغلات workflow workflows قابلة لاعادة الاستخدام github
هل تحتاج إلى مساعدة؟
هل واجهت مشكلة في هذه الأداة؟ أخبر فريقنا.
الإبلاغ عن مشكلة

أضف هذه الأداة المجانية إلى موقعك الخاص — انسخ والصق الكود أدناه.