deploy/README.md

Deploy Workflow

This is a workflow designed to handle automated deployment tasks. It leverages Docker containers, Composer, and various Node.js package managers to manage PHP and frontend dependencies, build projects, and deploy the application.

Usage Example

In this example, the deploy workflow is invoked with a custom Docker image, uses npm as the package manager, builds the frontend from the frontend directory, and passes customized Composer arguments. Secrets are provided for the SSH key and environment configuration.

jobs:
  deploy:
    uses: your-repo/.github/workflows/deploy.yml@main
    with:
      environment: production
      image: your-custom-image
      node-package-manager: npm
      frontend-directory: frontend
      composer-args: --no-dev
    secrets:
      ssh-private-key: ${{ secrets.PRODUCTION_SSH_PRIVATE_KEY }}
      env: ${{ secrets.PRODUCTION }}

Secrets

• ssh-private-key (required):

  • Type: string
  • Description: The SSH private key used to access the remote server for deployment. This is required for setting up SSH agent and making secure connections during the deployment process.

• env (required):

  • Type: string
  • Description: The contents of the .env file, which is passed in as a secret.

Input Parameters

• environment (required!):

  • Type: string
  • Description: The environment being deployed .e.g. production

• image (optional):

  • Type: string
  • Default: git.qlic.nl/qlic/deploy:php8.3-node22
  • Description: The Docker image used for deployment, which can be overridden if necessary.

• node-package-manager (optional):

  • Type: string
  • Description: The package manager to be used for the Node.js frontend build. Accepted values include npm, yarn, and pnpm.

• frontend-directory (optional):

  • Type: string
  • Description: Directory where the frontend code is located, if applicable. Used when switching to the appropriate directory for Node.js builds.

• composer-args (optional):

  • Type: string
  • Default:

    --verbose --prefer-dist --no-progress --no-interaction --no-dev --optimize-autoloader --ignore-platform-reqs
    

  • Description: Arguments passed to the Composer setup command for PHP dependency installation. These arguments can be customized based on specific requirements.

• username (optional):

  • Type: string
  • Default: ${{ vars.REGISTRY_USERNAME }}
  • Description: Username for the Docker registry authentication. Defaults to the value stored in vars.REGISTRY_USERNAME.

• password (optional):

  • Type: string
  • Default: ${{ vars.REGISTRY_PASSWORD }}
  • Description: Password for the Docker registry authentication. Defaults to the value stored in vars.REGISTRY_PASSWORD.

Workflow Job: deploy

The deploy job handles the core deployment process. It consists of multiple steps to set up dependencies, manage environment variables, build frontend assets, configure SSH, and deploy the application.

Steps

1. Checkout Code:

   • Action: actions/checkout@v4
   • Description: This step checks out the repository's code.

2. Setup Composer:

   • Action:
     Uses (https://git.qlic.nl/actions/setup-composer@main) to install PHP dependencies.
   • Inputs:
     • args: Composer arguments passed from the input composer-args.

3. Create .env File from Secret:

   • Run Command:

     echo "${{ secrets.env }}" > .env
     

   • Description: Writes the .env file using the secret passed through the env secret.

4. Build Frontend (Optional):

   • Conditional Step: Runs only if a node-package-manager is provided.
   • Run Commands:
     • If a frontend-directory is provided, it switches to that directory using cd.
     • It installs dependencies using the provided Node.js package manager (e.g., npm, yarn, or pnpm).
     • If a valid package manager is provided, it will also run the build command.
   • Description: Handles the frontend build process by installing Node.js dependencies and running the build script, if applicable.

5. Set Up SSH Agent:

   • Action: webfactory/ssh-agent@v0.5.3
   • Description: Sets up the SSH agent using the private key provided in the ssh-private-key secret. This is necessary for secure connections to the remote server during deployment.

6. Disable Strict Host Key Checking:

   • Run Command:

     echo "Host *" >> ~/.ssh/config
     echo "    StrictHostKeyChecking no" >> ~/.ssh/config
     

   • Description: Disables strict host key checking for SSH, allowing connections to new or unknown hosts without requiring manual confirmation.

7. Deploy Application:

   • Run Command:

     vendor/bin/dep deploy environment=production
     

   • Description: Runs the deployment script using the Deployer tool, targeting the production environment.