GitHub Action CI/CD Framework - Documentation Technique

1. Architecture Générale & Flux Principal

1.1 Flux d'Exécution Principal

┌─────────────────────────────────────────────────────────────────┐
│                     GITHUB ACTION TRIGGER                        │
└────────────────────────┬────────────────────────────────────────┘
                         │
         ┌───────────────┴───────────────┐
         │                               │
    [PRE-FLIGHT]                    [MAIN WORKFLOW]
         │                               │
    ├─ Load Config               ├─ Checkout Code
    ├─ Validate Token            ├─ Setup Environment
    ├─ Security Checks           ├─ PRE-HOOK (Webhook)
    ├─ Environment Lock          │
    └─ Release Blockers          ├─ PRE-PLUGIN (Script)
                                 │
                         ┌───────┴────────┐
                         │                │
                    [EXECUTE MODULES]    │
                         │                │
         ┌───────────────┼────────────┬───┴────────┐
         │               │            │            │
      [BUILD]       [TESTS]      [SECURITY]   [RELEASE]
         │               │            │            │
    ├─ Build App    ├─ Unit Tests ├─ Lint   ├─ Detect Changes
    ├─ Artifacts    ├─ Integration├─ Scan   ├─ Bump Version
    └─ Checksum     ├─ Coverage   ├─ SAST   ├─ Generate Changelog
                    └─ Bench      └─ Deps   ├─ Create Tag
                                           ├─ Create Release
                                           └─ Deploy
         │               │            │            │
         └───────────────┴────────────┴────────────┘
                         │
                  [POST-HOOK] (Webhook)
                         │
                  [POST-PLUGIN] (Script)
                         │
                 [GENERATE REPORTS]
                         │
              ├─ Compliance Report
              ├─ Deployment Report
              ├─ Audit Log Export
              └─ Artifacts Upload
                         │
                  [COMPLETE / ROLLBACK]

2. INPUTS DE L'ACTION

2.1 Configuration Générale

2.2 Authentification & Sécurité

2.3 Git & Branching

2.4 Versioning

2.5 Changelog & Release Notes

2.6 Tagging & Releases

2.7 Build & Artifacts

2.8 Tests & Qualité

2.9 Security & Scanning

2.10 Déploiement & Validation

2.11 Hooks & Plugins

2.12 Rapports & Audit

2.13 Gestion d'Erreurs & Retry

3. OUTPUTS DE L'ACTION

3.1 Versioning & Tags

3.2 Changelog & Release Notes

3.3 Build & Artifacts

3.4 Tests & Qualité

3.5 Security & Scanning

3.6 Déploiement

3.7 Rapports & Audit

3.8 Statuts Globaux

4. SCOPES & MODULES (Groupés par Type)

4.1 Scope: GIT & CONFIG

Module: Git Configuration

• git-user-name (input: string)
• git-user-email (input: string)
• auto-commit (input: boolean)
• auto-commit-message (input: string)
• auto-push (input: boolean)
• target-branch (input: string)

Module: Config Management

• config-source (input: choice)
• config-path (input: string)
• config-schema-check (input: boolean)
• load-config (function)
• config-lint (function)

Module: Branching Strategy

• trigger-branches (input: string)
• branch-protection-aware (input: boolean)
• branch-policy-check (input: boolean)
• review-enforcement (input: boolean)

4.2 Scope: VERSIONING

Module: Version Detection & Bumping

• detect-bump-type (function)
• bump (input: choice)
• version (input: string - override)
• initial (input: string)
• bump-type (output)
• current-version (output)
• previous-version (output)
• major-indicator (input: pattern)
• minor-indicator (input: pattern)
• patch-indicator (input: pattern)

Module: Semantic Versioning

• semantic-convention (input: choice)
• validate-semver (function)
• compare-versions (function)
• version-prefix (input: string)
• sync-version (input: string - paths)

Module: Tag Management

• create-tag (function)
• verify-tag (function)
• idempotent-check (function)
• tag-signature (input: boolean)
• tag-delete-on-failure (input: boolean)
• tag-name (output)
• tag-created (output)

4.3 Scope: CHANGELOG & RELEASE

Module: Changelog Generation

• generate-changelog (function)
• changelog-file (input: path)
• changelog-template (input: path)
• append-changelog (input: choice)
• extract-changelog (function)
• changelog-generated (output)
• changelog-content (output)

Module: Release Notes

• changelog-to-release-notes (function)
• release-notes (output)
• extract-changelog (function)

Module: Release Creation

• create-release (function)
• release-draft (input: boolean)
• release-prerelease (input: boolean)
• prerelease-suffix (input: string)
• release-created (output)
• release-url (output)

Module: Multi-Package Release

• package-release (function)
• monorepo-mode (input: boolean)
• detect-changed-packages (function)

4.4 Scope: BUILD & ARTIFACTS

Module: Build Process

• build-enabled (input: boolean)
• build-command (input: string)
• build-artifact-path (input: path)
• build-success (output)
• artifact-path (output)

Module: Artifact Management

• upload-artifact (input: boolean)
• artifact-retention-days (input: number)
• generate-version-file (function)
• generate-checksum (function)
• generate-sbom (function)
• artifact-signing (function)
• version-file-path (output)
• checksum-file (output)
• sbom-file-path (output)

Module: Artifact Verification

• artifact-verification (input: boolean)
• pre-deploy-check (function)
• pre-deploy-check-url (input: string)

4.5 Scope: TESTING

Module: Unit & Integration Tests

• tests-enabled (input: boolean)
• unit-tests-command (input: string)
• integration-tests-command (input: string)
• tests-passed (output)

Module: Coverage Analysis

• coverage-threshold (input: number)
• coverage-file-path (input: path)
• coverage-percentage (output)
• coverage-meets-threshold (output)

Module: Code Quality

• lint-enabled (input: boolean)
• lint-command (input: string)
• lint-report-parse (function)
• lint-report-path (input: path)
• lint-score-threshold (input: number)
• lint-passed (output)
• lint-score (output)

Module: Performance Benchmarking

• performance-benchmark-enabled (input: boolean)
• performance-benchmark-file (input: path)
• performance-regression-detected (output)
• performance-comparison (output)

4.6 Scope: SECURITY

Module: Dependency Scanning

• dependency-scan-enabled (input: boolean)
• dependency-scan-tool (input: choice)
• dependency-severity-threshold (input: choice)
• dependencies-vulnerable (output)
• vulnerable-packages (output)

Module: Static Analysis (SAST)

• sast-enabled (input: boolean)
• sast-tool (input: choice)
• sast-issues (output)

Module: Secret Scanning

• secret-scan-enabled (input: boolean)
• secrets-found (output)

Module: Code Signing & Verification

• commit-signature-check (function)
• commit-signature-check (input: boolean)
• tag-signature (input: boolean)
• gpg-key (input: string - secret)
• gpg-passphrase (input: string - secret)
• commit-signatures-valid (output)

Module: Supply Chain Security

• supply-chain-check (function)
• generate-sbom (function)
• sbom-format (input: choice)
• supply-chain-score (output)

Module: Token & Authentication

• github-token (input: string - secret)
• validate-token (function)
• token-scope-check (function)
• ssh-key (input: string - secret)

4.7 Scope: DEPLOYMENT

Module: Deployment Execution

• deploy-enabled (input: boolean)
• deploy-env (input: choice)
• deploy-command (input: string)
• deploy-matrix (input: string - JSON)
• deployment-status (output)
• deployment-environment (output)
• deployment-duration (output)

Module: Post-Deployment Validation

• post-deploy-validation (input: boolean)
• post-deploy-check-url (input: string)
• post-deploy-validation-passed (output)

Module: Rollback Strategy

• rollback-support (input: boolean)
• rollback-on-health-check-failure (input: boolean)
• rollback-performed (output)

4.8 Scope: HOOKS & PLUGINS

Module: Webhooks

• webhook-pre-flight-url (input: string)
• webhook-pre-flight-enabled (input: boolean)
• webhook-post-release-url (input: string)
• webhook-post-release-enabled (input: boolean)
• webhook-on-failure-url (input: string)
• webhook-on-failure-enabled (input: boolean)
• webhook-retry-attempts (input: number)
• webhook-timeout (input: number)

Module: Plugin Scripts

• plugin-pre-flight-script (input: path)
• plugin-pre-flight-enabled (input: boolean)
• plugin-post-release-script (input: path)
• plugin-post-release-enabled (input: boolean)
• plugin-on-failure-script (input: path)
• plugin-on-failure-enabled (input: boolean)
• plugin-timeout (input: number)
• plugin-error-strategy (input: choice)

4.9 Scope: REPORTING & AUDIT

Module: Report Generation

• generate-compliance-report (function)
• generate-deployment-report (function)
• generate-pre-flight-summary (function)
• compliance-report-path (output)
• deployment-report-path (output)
• pre-flight-summary-path (output)

Module: Audit Logging

• audit-log-export (function)
• audit-log-path (input: path)
• audit-log-path (output)

4.10 Scope: ERROR HANDLING & VALIDATION

Module: Retry & Timeout

• retry-on-failure (input: boolean)
• retry-attempts (input: number)
• retry-delay (input: number)
• timeout-on-failure (input: number)

Module: Release Validation

• ci-status-check (function)
• release-blockers-file (input: path)
• environment-lock (input: boolean)

Module: Commit Validation

• semantic-guard (function)
• commit-policy (function)
• commits-validated (output)

5. FUNCTIONS & SCRIPTS (Ordre d'Exécution)

5.1 Phase: PRE-FLIGHT (Avant tout)

5.2 Phase: CONFIG & GIT SETUP

5.3 Phase: BUILD

5.4 Phase: TESTS & QUALITY

5.5 Phase: SECURITY

5.6 Phase: VERSION & CHANGELOG

5.7 Phase: TAGGING & RELEASE

5.8 Phase: DEPLOYMENT (Optionnel)

5.9 Phase: REPORTING & CLEANUP

5.10 Phase: ERROR HANDLING (Si erreur détectée)

6. PLACEMENT DES HOOKS & PLUGINS DANS LE WORKFLOW

6.1 Timeline Complète avec Webhooks & Plugins

┌─ WORKFLOW START ──────────────────────────────────────────────────┐
│                                                                    │
│  [PRE-FLIGHT PHASE]                                                │
│  ├─ Load Config                                                   │
│  ├─ Validate Token                                                │
│  ├─ Environment Lock                                              │
│  │                                                                │
│  ├─► ⚡ WEBHOOK: pre-flight (si enabled)                          │
│  │   Payload: {config, token_valid, lock_status}                 │
│  │   Timeout: webhook-timeout (30s)                              │
│  │   Retry: webhook-retry-attempts (3)                           │
│  │                                                                │
│  ├─► 🔌 PLUGIN: pre-flight (si enabled)                           │
│  │   Script: plugin-pre-flight-script                            │
│  │   Timeout: plugin-timeout (300s)                              │
│  │   On Error: plugin-error-strategy (warn/error/ignore)         │
│  │                                                                │
│  ├─ Generate Pre-Flight Summary                                  │
│  └─ CI Status Check                                              │
│                                                                   │
│  [BUILD PHASE]                                                    │
│  ├─ Git User Config                                              │
│  ├─ Build Application                                            │
│  ├─ Generate Checksum                                            │
│  ├─ Artifact Verification                                        │
│  └─ Create Version File                                          │
│                                                                   │
│  [TEST PHASE]                                                     │
│  ├─ Unit Tests                                                   │
│  ├─ Integration Tests                                            │
│  ├─ Coverage Check                                               │
│  ├─ Lint Check                                                   │
│  └─ Performance Benchmark                                        │
│                                                                   │
│  [SECURITY PHASE]                                                 │
│  ├─ Secret Scan                                                  │
│  ├─ Dependency Scan                                              │
│  ├─ SAST Analysis                                                │
│  ├─ Commit Signature Check                                       │
│  ├─ Supply Chain Check                                           │
│  └─ Generate SBOM                                                │
│                                                                   │
│  [VERSION & CHANGELOG PHASE]                                     │
│  ├─ Get Commit Stats                                             │
│  ├─ Detect Bump Type                                             │
│  ├─ Calculate Version                                            │
│  ├─ Sync Version in Files                                        │
│  ├─ Generate Changelog                                           │
│  └─ Extract Release Notes                                        │
│                                                                   │
│  [TAGGING & RELEASE PHASE]                                       │
│  ├─ Verify Tag Doesn't Exist                                     │
│  ├─ Create Git Tag (+ GPG sign if enabled)                       │
│  ├─ Auto Commit (changelog/version files)                        │
│  ├─ Auto Push (commits + tag)                                    │
│  └─ Create GitHub Release                                        │
│                                                                   │
│  [DEPLOYMENT PHASE] (si deploy-enabled)                          │
│  ├─ Pre-Deploy Check (clean repo)                                │
│  ├─ Execute Deploy Command                                       │
│  ├─ Post-Deploy Validation (health check)                        │
│  └─ Rollback (si validation échoue)                              │
│                                                                   │
│  [POST-RELEASE PHASE]                                             │
│  ├─ Generate Reports (compliance, deployment)                    │
│  ├─ Export Audit Logs                                            │
│  ├─ Upload Artifacts                                             │
│  │                                                                │
│  ├─► ⚡ WEBHOOK: post-release (si enabled)                        │
│  │   Payload: {version, tag, release_url, all_stats}            │
│  │   Timeout: webhook-timeout (30s)                              │
│  │   Retry: webhook-retry-attempts (3)                           │
│  │                                                                │
│  ├─► 🔌 PLUGIN: post-release (si enabled)                         │
│  │   Script: plugin-post-release-script                          │
│  │   Args: VERSION TAG RELEASE_URL                               │
│  │   Timeout: plugin-timeout (300s)                              │
│  │   On Error: plugin-error-strategy (warn/error/ignore)         │
│  │                                                                │
│  └─ WORKFLOW COMPLETE ✓                                           │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

┌─ ERROR / FAILURE ─────────────────────────────────────────────────┐
│                                                                    │
│  [ERROR DETECTED]                                                  │
│  ├─ Retry Logic (si retry-on-failure)                            │
│  ├─ Rollback Changes (si applicable)                             │
│  ├─ Delete Tag (si tag-delete-on-failure)                        │
│  │                                                                │
│  ├─► ⚡ WEBHOOK: on-failure (si enabled)                          │
│  │   Payload: {error_message, phase, attempt, timestamp}        │
│  │   Timeout: webhook-timeout (30s)                              │
│  │   Retry: webhook-retry-attempts (3)                           │
│  │                                                                │
│  ├─► 🔌 PLUGIN: on-failure (si enabled)                           │
│  │   Script: plugin-on-failure-script                            │
│  │   Args: ERROR_MESSAGE PHASE ATTEMPT                           │
│  │   Timeout: plugin-timeout (300s)                              │
│  │   On Error: ignore (pour ne pas masquer erreur principale)    │
│  │                                                                │
│  └─ WORKFLOW FAILED ✗                                             │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

6.2 Détails des Payloads Webhooks

WEBHOOK: pre-flight

{
  "event": "pre-flight",
  "timestamp": "2024-01-15T10:30:00Z",
  "repository": "owner/repo",
  "branch": "main",
  "config": {
    "version_prefix": "v",
    "initial_version": "0.1.0",
    "enable_deploy": false
  },
  "validation": {
    "token_valid": true,
    "lock_acquired": false,
    "ci_status": "success"
  },
  "environment": "production"
}

WEBHOOK: post-release

{
  "event": "post-release",
  "timestamp": "2024-01-15T10:45:00Z",
  "repository": "owner/repo",
  "branch": "main",
  "release": {
    "version": "1.2.3",
    "tag": "v1.2.3",
    "url": "https://github.com/.../releases/tag/v1.2.3",
    "created_at": "2024-01-15T10:44:00Z"
  },
  "stats": {
    "commits_since_last": 12,
    "build_duration": 120,
    "tests_passed": true,
    "coverage": 92.5,
    "security_issues": 0,
    "deployment_status": "skipped"
  },
  "artifacts": [
    {"name": "build.tar.gz", "size": 2048576, "checksum": "sha256:..."}
  ]
}

WEBHOOK: on-failure

{
  "event": "on-failure",
  "timestamp": "2024-01-15T10:40:00Z",
  "repository": "owner/repo",
  "error": {
    "message": "Tests failed: 2 unit tests",
    "phase": "testing",
    "code": "TEST_FAILURE"
  },
  "context": {
    "attempt": 1,
    "max_attempts": 3,
    "retry_in_seconds": 5
  }
}

6.3 Paramètres des Plugins/Scripts

Plugin: pre-flight

#!/bin/bash
# Arguments passés en variables d'environnement
GITHUB_TOKEN="$1"
CONFIG_PATH="$2"
DEBUG_MODE="$3"

# Le script doit retourner:
# - Code 0: succès (continue)
# - Code 1: erreur bloquante (selon plugin-error-strategy)
# - Code 2: warning (toujours)

echo "[AUDIT] Pre-flight validation started"
exit 0

Plugin: post-release

#!/bin/bash
# Arguments positionnels
VERSION="$1"
TAG="$2"
RELEASE_URL="$3"
DRY_RUN="$4"

# Variables d'environnement disponibles
# - GITHUB_REPOSITORY
# - GITHUB_ACTOR
# - GITHUB_SHA
# - All action outputs

echo "[AUDIT] Publishing release notification..."
exit 0

7. MATRICE DE CONFIGURATION PAR CAS D'USAGE

7.1 Configuration Minimale (Quick Release)

trigger-branches: main
auto-commit: true
auto-push: true
generate-changelog: true
create-tag: true
create-release: true

7.2 Configuration Monorepo (Multiple Packages)

monorepo-mode: true
package-release: true
detect-changed-packages: true
sync-version: "package.json,packages/*/package.json,Chart.yaml"
deploy-matrix: '{"dev":"","staging":"-rc","prod":""}'

7.3 Configuration Sécurité Maximale

secret-scan-enabled: true
dependency-scan-enabled: true
sast-enabled: true
commit-signature-check: true
tag-signature: true
supply-chain-check: true
generate-sbom: true
generate-compliance-report: true

7.4 Configuration Multi-Environnements avec Déploiement

deploy-enabled: true
deploy-matrix: '{"dev":"-dev","staging":"-rc","prod":""}'
post-deploy-validation: true
post-deploy-check-url: "https://api.example.com/health"
rollback-support: true

8. EXEMPLE D'UTILISATION COMPLÈTE

action.yml

name: 'Instant Release - CI/CD Framework'
description: 'Modular GitHub Action for complete CI/CD automation'

inputs:
  # Git & Config (REQUIRED)
  github-token:
    description: 'GitHub token with contents:write permission'
    required: true
  git-user-name:
    description: 'Git user name for commits'
    default: 'github-actions[bot]'
  git-user-email:
    description: 'Git user email'
    default: 'github-actions[bot]@github.com'

  # Versioning
  bump:
    description: 'Version bump type: auto|major|minor|patch'
    default: 'auto'
  generate-changelog:
    description: 'Generate changelog'
    default: 'true'
  create-tag:
    description: 'Create Git tag'
    default: 'true'
  create-release:
    description: 'Create GitHub Release'
    default: 'true'

  # Build
  build-enabled:
    description: 'Enable build step'
    default: 'true'
  build-command:
    description: 'Build command'
    default: 'npm run build'

  # Tests
  tests-enabled:
    description: 'Enable tests'
    default: 'true'
  unit-tests-command:
    description: 'Unit tests command'
    default: 'npm test'
  coverage-threshold:
    description: 'Minimum coverage percentage'
    default: '80'

  # Security
  dependency-scan-enabled:
    description: 'Enable dependency scanning'
    default: 'true'
  secret-scan-enabled:
    description: 'Enable secret scanning'
    default: 'false'

  # Deployment
  deploy-enabled:
    description: 'Enable deployment'
    default: 'false'
  deploy-command:
    description: 'Deploy command'

  # Webhooks & Plugins
  webhook-post-release-enabled:
    description: 'Enable post-release webhook'
    default: 'false'
  webhook-post-release-url:
    description: 'Post-release webhook URL'
  plugin-post-release-enabled:
    description: 'Enable post-release plugin'
    default: 'false'
  plugin-post-release-script:
    description: 'Post-release plugin script path'

  # Debug & Dry-run
  debug:
    description: 'Enable debug mode'
    default: 'false'
  dry-run:
    description: 'Enable dry-run mode'
    default: 'false'

outputs:
  current-version:
    description: 'Current version created'
    value: ${{ steps.version.outputs.current-version }}
  bump-type:
    description: 'Bump type applied'
    value: ${{ steps.version.outputs.bump-type }}
  tag-created:
    description: 'Whether tag was created'
    value: ${{ steps.tag.outputs.tag-created }}
  changelog-generated:
    description: 'Whether changelog was generated'
    value: ${{ steps.changelog.outputs.changelog-generated }}
  release-url:
    description: 'GitHub Release URL'
    value: ${{ steps.release.outputs.release-url }}
  deployment-status:
    description: 'Deployment status'
    value: ${{ steps.deploy.outputs.deployment-status }}



runs:
  using: 'composite'
  steps:
    # Pre-flight
    - name: Pre-flight checks
      run: ${{ github.action_path }}/scripts/pre-flight.sh
      shell: bash
      env:
        GITHUB_TOKEN: ${{ inputs.github-token }}
        DEBUG: ${{ inputs.debug }}
        DRY_RUN: ${{ inputs.dry-run }}

    # Webhook pre-flight
    - name: Webhook pre-flight
      if: ${{ inputs.webhook-pre-flight-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/webhook-call.sh
      shell: bash
      env:
        WEBHOOK_URL: ${{ inputs.webhook-pre-flight-url }}
        WEBHOOK_EVENT: 'pre-flight'
        WEBHOOK_TIMEOUT: ${{ inputs.webhook-timeout }}

    # Plugin pre-flight
    - name: Plugin pre-flight
      if: ${{ inputs.plugin-pre-flight-enabled == 'true' }}
      run: |
        bash "${{ inputs.plugin-pre-flight-script }}" \
          "${{ inputs.github-token }}" \
          "${{ inputs.config-path }}" \
          "${{ inputs.debug }}"
      shell: bash
      timeout-minutes: ${{ inputs.plugin-timeout }}

    # Build
    - name: Build
      if: ${{ inputs.build-enabled == 'true' }}
      run: ${{ inputs.build-command }}
      shell: bash

    # Tests
    - name: Unit Tests
      if: ${{ inputs.tests-enabled == 'true' }}
      run: ${{ inputs.unit-tests-command }}
      shell: bash

    - name: Coverage Check
      if: ${{ inputs.tests-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/coverage-check.sh
      shell: bash
      env:
        COVERAGE_THRESHOLD: ${{ inputs.coverage-threshold }}
        COVERAGE_FILE: ${{ inputs.coverage-file-path }}

    - name: Lint
      if: ${{ inputs.lint-enabled == 'true' }}
      run: ${{ inputs.lint-command }}
      shell: bash

    # Security
    - name: Dependency Scan
      if: ${{ inputs.dependency-scan-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/dependency-scan.sh
      shell: bash
      env:
        SCAN_TOOL: ${{ inputs.dependency-scan-tool }}
        SEVERITY_THRESHOLD: ${{ inputs.dependency-severity-threshold }}

    - name: Secret Scan
      if: ${{ inputs.secret-scan-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/secret-scan.sh
      shell: bash

    - name: SAST Analysis
      if: ${{ inputs.sast-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/sast-analysis.sh
      shell: bash
      env:
        SAST_TOOL: ${{ inputs.sast-tool }}

    # Versioning
    - name: Calculate Version
      id: version
      run: ${{ github.action_path }}/scripts/calculate-version.sh
      shell: bash
      env:
        BUMP: ${{ inputs.bump }}
        VERSION: ${{ inputs.version }}
        INITIAL: ${{ inputs.initial }}
        MAJOR_INDICATOR: ${{ inputs.major-indicator }}
        MINOR_INDICATOR: ${{ inputs.minor-indicator }}
        PATCH_INDICATOR: ${{ inputs.patch-indicator }}

    - name: Sync Version Files
      if: ${{ inputs.sync-version != '' }}
      run: ${{ github.action_path }}/scripts/sync-version.sh
      shell: bash
      env:
        VERSION: ${{ steps.version.outputs.current-version }}
        SYNC_PATHS: ${{ inputs.sync-version }}

    # Changelog
    - name: Generate Changelog
      if: ${{ inputs.generate-changelog == 'true' }}
      id: changelog
      run: ${{ github.action_path }}/scripts/generate-changelog.sh
      shell: bash
      env:
        CHANGELOG_FILE: ${{ inputs.changelog-file }}
        CHANGELOG_TEMPLATE: ${{ inputs.changelog-template }}
        VERSION: ${{ steps.version.outputs.current-version }}

    # Tagging & Release
    - name: Create Tag
      if: ${{ inputs.create-tag == 'true' }}
      id: tag
      run: ${{ github.action_path }}/scripts/create-tag.sh
      shell: bash
      env:
        VERSION: ${{ steps.version.outputs.current-version }}
        VERSION_PREFIX: ${{ inputs.version-prefix }}
        TAG_SIGNATURE: ${{ inputs.tag-signature }}
        GPG_KEY: ${{ inputs.gpg-key }}
        DRY_RUN: ${{ inputs.dry-run }}

    - name: Auto Commit
      if: ${{ inputs.auto-commit == 'true' && inputs.create-tag == 'true' }}
      run: ${{ github.action_path }}/scripts/auto-commit.sh
      shell: bash
      env:
        GIT_USER_NAME: ${{ inputs.git-user-name }}
        GIT_USER_EMAIL: ${{ inputs.git-user-email }}
        COMMIT_MESSAGE: ${{ inputs.auto-commit-message }}
        VERSION: ${{ steps.version.outputs.current-version }}
        DRY_RUN: ${{ inputs.dry-run }}

    - name: Auto Push
      if: ${{ inputs.auto-push == 'true' && inputs.create-tag == 'true' }}
      run: ${{ github.action_path }}/scripts/auto-push.sh
      shell: bash
      env:
        GITHUB_TOKEN: ${{ inputs.github-token }}
        TARGET_BRANCH: ${{ inputs.target-branch }}
        DRY_RUN: ${{ inputs.dry-run }}

    - name: Create Release
      if: ${{ inputs.create-release == 'true' && inputs.create-tag == 'true' }}
      id: release
      run: ${{ github.action_path }}/scripts/create-release.sh
      shell: bash
      env:
        GITHUB_TOKEN: ${{ inputs.github-token }}
        TAG: ${{ steps.tag.outputs.tag-name }}
        RELEASE_NOTES: ${{ steps.changelog.outputs.release-notes }}
        DRAFT: ${{ inputs.release-draft }}
        PRERELEASE: ${{ inputs.release-prerelease }}
        DRY_RUN: ${{ inputs.dry-run }}

    # Deployment
    - name: Pre-Deploy Check
      if: ${{ inputs.deploy-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/pre-deploy-check.sh
      shell: bash

    - name: Deploy
      if: ${{ inputs.deploy-enabled == 'true' }}
      id: deploy
      run: ${{ inputs.deploy-command }}
      shell: bash
      env:
        ENVIRONMENT: ${{ inputs.deploy-env }}
        VERSION: ${{ steps.version.outputs.current-version }}
        DRY_RUN: ${{ inputs.dry-run }}

    - name: Post-Deploy Validation
      if: ${{ inputs.post-deploy-validation == 'true' && inputs.deploy-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/post-deploy-validation.sh
      shell: bash
      env:
        CHECK_URL: ${{ inputs.post-deploy-check-url }}
        TIMEOUT: 300

    # Reporting
    - name: Generate Reports
      if: ${{ always() }}
      run: ${{ github.action_path }}/scripts/generate-reports.sh
      shell: bash
      env:
        GENERATE_COMPLIANCE: ${{ inputs.generate-compliance-report }}
        GENERATE_DEPLOYMENT: ${{ inputs.generate-deployment-report }}
        VERSION: ${{ steps.version.outputs.current-version }}

    # Webhook post-release
    - name: Webhook post-release
      if: ${{ success() && inputs.webhook-post-release-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/webhook-call.sh
      shell: bash
      env:
        WEBHOOK_URL: ${{ inputs.webhook-post-release-url }}
        WEBHOOK_EVENT: 'post-release'
        VERSION: ${{ steps.version.outputs.current-version }}
        TAG: ${{ steps.tag.outputs.tag-name }}
        RELEASE_URL: ${{ steps.release.outputs.release-url }}

    # Plugin post-release
    - name: Plugin post-release
      if: ${{ success() && inputs.plugin-post-release-enabled == 'true' }}
      run: |
        bash "${{ inputs.plugin-post-release-script }}" \
          "${{ steps.version.outputs.current-version }}" \
          "${{ steps.tag.outputs.tag-name }}" \
          "${{ steps.release.outputs.release-url }}" \
          "${{ inputs.dry-run }}"
      shell: bash
      timeout-minutes: ${{ inputs.plugin-timeout }}

    # Error handling - Webhook on-failure
    - name: Webhook on-failure
      if: ${{ failure() && inputs.webhook-on-failure-enabled == 'true' }}
      run: ${{ github.action_path }}/scripts/webhook-call.sh
      shell: bash
      env:
        WEBHOOK_URL: ${{ inputs.webhook-on-failure-url }}
        WEBHOOK_EVENT: 'on-failure'
        ERROR_MESSAGE: ${{ job.status }}
        PHASE: 'workflow'

    # Error handling - Plugin on-failure
    - name: Plugin on-failure
      if: ${{ failure() && inputs.plugin-on-failure-enabled == 'true' }}
      run: |
        bash "${{ inputs.plugin-on-failure-script }}" \
          "${{ job.status }}" \
          "workflow" \
          "1"
      shell: bash
      timeout-minutes: ${{ inputs.plugin-timeout }}
      continue-on-error: true

    # Cleanup
    - name: Upload Artifacts
      if: ${{ always() && inputs.upload-artifact == 'true' }}
      uses: actions/upload-artifact@v3
      with:
        name: release-artifacts
        path: |
          ${{ inputs.changelog-file }}
          ${{ steps.version.outputs.version-file-path }}
        retention-days: ${{ inputs.artifact-retention-days }}

9. GUIDE D'INTÉGRATION DANS UN WORKFLOW

9.1 Workflow Simple (Automatique)

name: Release

on:
  push:
    branches: [ main ]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Release
        uses: ./
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          build-command: npm run build
          unit-tests-command: npm test

9.2 Workflow Avancé (Avec Webhooks & Plugins)

name: Advanced Release

on:
  push:
    branches: [ main ]
  workflow_dispatch:
    inputs:
      bump:
        description: 'Version bump'
        required: false
        default: 'auto'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Release with Webhooks
        uses: ./
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          bump: ${{ github.event.inputs.bump || 'auto' }}

          # Build & Tests
          build-command: npm run build
          unit-tests-command: npm test
          coverage-threshold: 85

          # Security
          dependency-scan-enabled: 'true'
          secret-scan-enabled: 'true'
          sast-enabled: 'true'
          sast-tool: codeql

          # Deployment
          deploy-enabled: 'true'
          deploy-command: npm run deploy
          deploy-env: production
          post-deploy-validation: 'true'
          post-deploy-check-url: https://api.example.com/health

          # Webhooks
          webhook-post-release-enabled: 'true'
          webhook-post-release-url: ${{ secrets.WEBHOOK_URL }}

          # Plugins
          plugin-post-release-enabled: 'true'
          plugin-post-release-script: ./scripts/post-release.sh

          # Reporting
          generate-compliance-report: 'true'
          generate-deployment-report: 'true'
          audit-log-export: 'true'

10. STRUCTURE DES FICHIERS DU PROJET

instantrelease/
├── action.yml                          # Définition action
├── README.md                           # Documentation principale
├── SPECIFICATION.md                    # Cette documentation
│
├── scripts/
│   ├── lib/                           # Librairies réutilisables
│   │   ├── logger.sh                 # Logging avec [AUDIT], [DEBUG]
│   │   ├── utils.sh                  # Fonctions utilitaires
│   │   ├── git.sh                    # Opérations Git
│   │   ├── github-api.sh             # Interactions GitHub API
│   │   └── validators.sh             # Validations (semver, yaml, etc.)
│   │
│   ├── pre-flight.sh                 # Phase pré-vol
│   ├── webhook-call.sh               # Appels webhooks
│   │
│   ├── build/
│   │   ├── build.sh                  # Build application
│   │   ├── generate-checksum.sh      # Génération checksums
│   │   └── generate-version-file.sh  # Création VERSION file
│   │
│   ├── tests/
│   │   ├── unit-tests.sh             # Tests unitaires
│   │   ├── coverage-check.sh         # Vérification couverture
│   │   ├── lint.sh                   # Linting
│   │   └── performance-benchmark.sh  # Benchmarks
│   │
│   ├── security/
│   │   ├── dependency-scan.sh        # Scan dépendances
│   │   ├── secret-scan.sh            # Scan secrets
│   │   ├── sast-analysis.sh          # Analyse SAST
│   │   ├── commit-signature-check.sh # Vérification signatures
│   │   └── supply-chain-check.sh     # Vérification supply chain
│   │
│   ├── versioning/
│   │   ├── calculate-version.sh      # Calcul version
│   │   ├── detect-bump-type.sh       # Détection bump
│   │   ├── validate-semver.sh        # Validation semver
│   │   └── sync-version.sh           # Sync fichiers version
│   │
│   ├── changelog/
│   │   ├── generate-changelog.sh     # Génération changelog
│   │   ├── extract-changelog.sh      # Extraction dernière entrée
│   │   └── changelog-to-release-notes.sh # Conversion
│   │
│   ├── release/
│   │   ├── create-tag.sh             # Création tag
│   │   ├── verify-tag.sh             # Vérification tag
│   │   ├── auto-commit.sh            # Commit auto
│   │   ├── auto-push.sh              # Push auto
│   │   └── create-release.sh         # Création GitHub Release
│   │
│   ├── deploy/
│   │   ├── pre-deploy-check.sh       # Pré-déploiement
│   │   ├── post-deploy-validation.sh # Post-déploiement
│   │   └── rollback.sh               # Rollback
│   │
│   └── reporting/
│       ├── generate-reports.sh       # Génération rapports
│       ├── compliance-report.sh      # Rapport audit
│       └── audit-log-export.sh       # Export logs audit
│
├── templates/
│   ├── changelog-default.hbs         # Template changelog défaut
│   ├── compliance-report.hbs         # Template rapport
│   └── pre-flight-summary.hbs        # Template résumé pré-vol
│
└── tests/
    ├── unit/                         # Tests unitaires des scripts
    └── integration/                  # Tests d'intégration

11. RÉSUMÉ EXÉCUTIF

Points Clés de l'Architecture

✅ Modularité : Chaque scope est indépendant et can-disable
✅ Robustesse : Retry logic, timeout, error handling complets
✅ Transparence : Logs [AUDIT], [DEBUG], rapports détaillés
✅ Extensibilité : Webhooks + Plugins à 3 moments clés
✅ Sécurité : Scanning complet, signing, supply chain
✅ Monorepo-Ready : Support multi-packages avec versioning indépendant
✅ Cloud-Native : Conçu pour GitHub Actions, intégrable ailleurs

Timeline d'Exécution Typique

PRE-FLIGHT (30s)
  ↓
BUILD (120s)
  ↓
TESTS + QUALITY (180s)
  ↓
SECURITY (120s)
  ↓
VERSIONING + CHANGELOG (30s)
  ↓
TAGGING + RELEASE (15s)
  ↓
DEPLOYMENT (300s, si enabled)
  ↓
REPORTING + WEBHOOKS (30s)
  ↓
TOTAL: 5-10 minutes