Thiết lập Github Actions

Bước 1: Tạo Github Actions 

Bước 2: Tìm kiếm và config Laravel Github Actions được cung cấp bởi Github

Bước 3: Tạo file Github workflow

Ở bước này các bạn cần phải đổi lại tên của workflow,với mình đổi thành cicd.yml và sau đó copy đoạn code template workflow của mình đã chuẩn bị sãn cho mọi người click vào đây để xem và paste và trong file workflow của các bạn nhé ! Mình sẽ giải thích từng chút một về nó ở bước sau. Cuối cùng hãy nhấn commit changes.

Ở bước tiếp theo dưới đây các bạn có thể tạo ra 1 branch mới hoặc tạo trực tiếp vào nhánh chính (master) của mình, do mình làm trên 1 nhánh duy nhất luôn nên mình tạo trực tiếp nha, còn trong thực tế các bạn làm có người review thì , nên tạo ra 1 nhánh riêng là tốt nhất.

Bước 4: Hiểu và chỉnh sửa workflow

Để hiểu được một workflow nó gồm những thuộc tính gì và từng thuộc tính nó hoạt động như thế nào thì các bạn có thể xem bài viết Cấu trúc cơ bản của một workflow Github Actions trước hoặc có thể vào doc của Github Actions để đọc thêm nhé! Ok chúng ta sẽ cùng nhau bóc tách đoạn code worklow template mình đã chuẩn bị cho các bạn trước đó nhé!

Bóc tách 1:

name: CI-CD

on:
  pull_request:
    branches:
      - master
  push:
    branches:
      - master

Ở bóc tách 1 này sẽ bao gồm:

1. name: Tên workflow của bạn.
2. on: Xác định các sự kiện GitHub mà workflow này sẽ phản ứng và thực thi. Trong ví dụ trên nó sẽ được thực thi khi có một pull request hoặc push vào nhánh dev, trong thực tế tùy thuộc vào nhánh mà bạn đang muốn thực thi hãy sửa lại cho phù hợp với dự án của bạn.

Như các bạn đã biết trong một workflow thì luôn luôn có một hoặc nhiều jobs, trong demo này mình đã chia ra là 3 jobs, chúng ta sẽ cùng nhau hiểu chi tiết về từng job này nhé!

Job 1: php-cs

jobs:
  php-cs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PHP
        uses: shivammathur/setup-php@master
        with:
          php-version: "8.1"
          php_extensions: mbstring bcmath http gd zip
          version: 2
      - name: Laravel Setup Testing Environtment
        run: |
          cp .env.example .env
          composer install
          php artisan key:generate
          chmod -R 777 storage bootstrap/cache
      - name: Check coding convention by PHP_CodeSniffer
        run: ./vendor/bin/phpcs
      # - name: PHP mess detector
      #   run: ./vendor/bin/phpmd app,database,routes,tests text phpmd.xml

php-cs là một tính năng check coding convention trước khi chúng ta push code lên nhánh chính, chúng ta cần đảm bảo rằng code của chúng ta phải clean và đúng với các chuẩn coding convention mà chúng ta đặt ra để tạo ra một sản phẩm chất lượng thì bạn nên dùng job này, nó chỉ là optional nếu các bạn không muốn có job này trong dự án của các bạn thì các bạn có thể xóa hoặc comment lại nhé! Vậy Job php-cs bao gồm những gì cùng khám phá nhé!

1. runs-on: ubuntu-latest: Xác định hệ điều hành và môi trường mà các job sẽ chạy, trong ví dụ này mình đang sử dụng ubuntu với phiên bản latest.
2. steps: Hành động cụ thể mà bạn muốn thực hiện trong quá trình CI/CD. Sẽ có rất nhiều step trong một folow và chúng sẽ chạy tuần tự, bạn cứ hiểu 1 gạch đầu dòng là một step.
   1. Step 1: 
      • uses được sử dụng để sử dụng một action có sẵn từ thư viện của GitHub. Trong ví dụ này mình sử dụng thư viện actions/checkout@v3, thư viện actions/checkout@v3 là là một action sẵn có được cung cấp bởi GitHub để tự động checkout mã nguồn của bạn từ một repository Git vào môi trường làm việc của workflow.
   2. Step 2:
      1. name: Đây là tên của step trong workflow. Trong trường hợp này, step này được gọi là "Setup PHP", nghĩa là nó sẽ thiết lập môi trường PHP cho workflow.
      2. uses: Đây là action mà mình đang sử dụng. Trong trường hợp này, mình đang sử dụng action shivammathur/setup-php 1 thư viện của github action với nhánh là master. Điều này có nghĩa là mình đang sử dụng action được tạo ra bởi Shivam Mathur để thiết lập môi trường PHP.

      3. with: Đây là phần các tham số (options) được truyền cho action. Cụ thể trong trường hợp này:

         • php-version: Đây là phiên bản của PHP mà mình muốn cài đặt. Trong trường hợp này, phiên bản được chọn là "8.1".

         • php_extensions: Đây là các extension PHP mà mình muốn cài đặt kèm theo. Trong trường hợp này, mình đang cài đặt các extension như mbstring, bcmath, http, gd, và zip.

         • version: Đây là phiên bản của action shivammathur/setup-php mà mình muốn sử dụng. Trong trường hợp này, mình đang sử dụng phiên bản 2.

   3. Step 3:
      1. name: Tên của bước trong workflow. Trong trường hợp này, bước này được gọi là "Laravel Setup Testing Environment", nghĩa là nó sẽ thiết lập môi trường thử nghiệm cho Laravel.

      2. run: Đây là nơi bạn có thể viết các lệnh shell để thực thi trong môi trường làm việc của GitHub Actions. Trong trường hợp này, có một loạt các lệnh shell được thực thi.

         • cp .env.example .env: Dòng này sao chép tệp .env.example thành .env, một cách thông thường để tạo tệp cấu hình cho Laravel. Tệp .env thường chứa cấu hình cho ứng dụng Laravel, ví dụ như cấu hình cơ sở dữ liệu.

         • composer install: Dòng này sử dụng Composer để cài đặt các gói PHP được khai báo trong tệp composer.json. Composer là một công cụ quản lý gói PHP phổ biến được sử dụng trong các dự án Laravel.

         • php artisan key:generate: Dòng này thực thi lệnh php artisan key:generate, một lệnh Laravel để tạo ra một khóa ứng dụng mới. Khóa này thường được sử dụng để mã hóa dữ liệu trong ứng dụng Laravel.

         • chmod -R 777 storage bootstrap/cache: Dòng này sửa đổi quyền truy cập của thư mục storage và bootstrap/cache để đảm bảo rằng Laravel có quyền ghi vào các thư mục này.

   4. Step 4:
      1. name: Tên của bước trong workflow. Trong trường hợp này, bước này được gọi là "Check coding convention by PHP_CodeSniffer", nghĩa là nó sẽ kiểm tra các coding convention về rules code bằng PHP_CodeSniffer.

      2. run: Đây là nơi bạn có thể viết các lệnh shell để thực thi trong môi trường làm việc của GitHub Actions. Trong trường hợp này, có một dòng lệnh shell được thực hiện.

         • ./vendor/bin/phpcs: Dòng này thực hiện lệnh phpcs từ thư mục ./vendor/bin. Đây là lệnh của PHP_CodeSniffer để kiểm tra mã nguồn PHP dựa trên các tập lệnh và cấu hình đã được cài đặt trong dự án. Bằng cách chạy lệnh này, bạn đang kiểm tra tuân thủ của mã nguồn PHP với các quy tắc về quy ước mã đã được định nghĩa. Nếu có bất kỳ vi phạm nào, PHP_CodeSniffer sẽ hiển thị các cảnh báo hoặc lỗi tương ứng.

Job 2: php-unit

php-unit:
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_DATABASE: maverickpass_testing
          MYSQL_ROOT_PASSWORD: root
          MYSQL_ALLOW_EMPTY_PASSWORD: yes
        ports:
          - 3306:3306
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
    steps:
      - uses: actions/checkout@v3
        with:
          # Disabling shallow clone is recommended for improving relevancy of reporting
          fetch-depth: 0
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1
          extensions: mbstring, bcmath, php-http, gd, zip
          tools: composer:v2
      - name: Laravel Setup Testing Environtment
        run: |
          cp .env.example .env
          composer install
          php artisan key:generate
          chmod -R 777 storage bootstrap/cache
      - name: npm install and build
        run: |
          npm install
          npm run build
      - name: Run Tests
        run: |
          php artisan migrate --env=testing --force
          php artisan key:generate
          ./vendor/bin/phpunit --coverage-clover=coverage-report.xml

1. php-unit: Đây là tên của công việc (job) trong workflow, được đặt tên là "php-unit".

2. runs-on: Đây là môi trường mà job sẽ chạy trên. Trong trường hợp này, job này sẽ chạy trên ubuntu-latest.

3. services: Đây là một phần của cấu hình service, được sử dụng để chạy các dịch vụ phụ trợ như cơ sở dữ liệu trong quá trình thử nghiệm.

   • mysql: Đây là tên của dịch vụ MySQL được sử dụng. Ở đây, một container MySQL phiên bản 8.0 được khởi chạy với một số cấu hình cụ thể như cơ sở dữ liệu, mật khẩu và cổng.

4. steps: Đây là danh sách các bước cần thực thi trong job. Mỗi bước thực hiện một hoặc nhiều tác vụ cụ thể.

   • actions/checkout@v3: Bước này sử dụng hành động actions/checkout để checkout mã nguồn từ repository.

   • Setup PHP: Bước này sử dụng hành động shivammathur/setup-php để cài đặt và cấu hình một môi trường PHP với các phiên bản và các extension được chỉ định.

   • Laravel Setup Testing Environment: Bước này thực hiện một loạt các tác vụ như sao chép tệp .env.example thành .env, cài đặt các gói PHP thông qua Composer, tạo khóa ứng dụng Laravel, và thiết lập quyền truy cập cho các thư mục storage và bootstrap/cache.

   • npm install and build: Bước này sử dụng npm để cài đặt các gói JavaScript cần thiết và sau đó build ứng dụng nếu có.

   • Run Tests: Bước này thực hiện các bài kiểm tra và thử nghiệm, trong đó bao gồm việc thực hiện các lệnh như migrate cơ sở dữ liệu, tạo khóa ứng dụng Laravel (lần nữa), và chạy các test bằng PHPUnit, và xuất kết quả phủ sóng (code coverage) vào một tệp XML.

     • php artisan migrate --env=testing --force: Dòng này thực thi lệnh php artisan migrate để chạy các file migration trong môi trường testing (--env=testing). Migration là cách Laravel quản lý cấu trúc cơ sở dữ liệu, và bằng cách chạy migration, bạn đảm bảo rằng cơ sở dữ liệu testing của bạn đang ở trạng thái cập nhật nhất trước khi chạy các bài kiểm tra. Tùy chọn --force được sử dụng để không cần xác nhận lại trước khi chạy các migration.

     • php artisan key:generate: Dòng này thực hiện lệnh php artisan key:generate, một lệnh Laravel để tạo ra một khóa ứng dụng mới. Khóa này thường được sử dụng để mã hóa dữ liệu trong ứng dụng Laravel. Trong trường hợp này, lệnh này có thể đang được thực hiện để tạo ra một khóa mới cho môi trường testing.

     • ./vendor/bin/phpunit --coverage-clover=coverage-report.xml: Dòng này thực thi các test bằng PHPUnit, một framework kiểm tra cho PHP. Tùy chọn --coverage-clover được sử dụng để xuất báo cáo phủ sóng (code coverage) của các test vào một tệp XML có tên là coverage-report.xml. Code coverage báo cáo về phần code mà các bài kiểm tra của bạn đã thực hiện và kiểm tra.

Job 3: deploy-stagging

deploy-stagging:
    name: Deploy Stagging
    runs-on: ubuntu-latest
    needs: [php-cs, php-unit]
    if: github.ref == 'refs/heads/master'
    steps:
      - uses: actions/checkout@v2
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "8.1"
      - name: Laravel Setup
        run: |
          composer install
      - name: Deploy
        uses: deployphp/action@v1
        with:
          private-key: ${{ secrets.STG_PRIVATE_KEY }}
          dep: deploy app.dev
          ssh-config: |
            Host app.dev
              HostName ${{ secrets.STG_HOST }}
              User ${{ secrets.STG_USER }}
              StrictHostKeyChecking no

1. deploy-stagging: Đây là tên của công việc (job) trong workflow, được đặt tên là "Deploy Stagging".

2. name: Tên của công việc. Trong trường hợp này, nó được gọi là "Deploy Stagging".

3. runs-on: Đây là môi trường mà job sẽ chạy trên. Trong trường hợp này, job này sẽ chạy trên ubuntu-latest.

4. needs: Đây là danh sách các jobs mà job hiện tại phụ thuộc vào. Job này cần các job php-cs và php-unit đã chạy trước đó để hoàn thành trước khi nó được thực hiện.

5. if: Điều kiện để xác định xem job này có được chạy hay không. Trong trường hợp này, nó chỉ sẽ chạy nếu nhánh hiện tại là master.

6. steps: Đây là danh sách các bước cần thực thi trong job. Mỗi bước thực hiện một hoặc nhiều tác vụ cụ thể.

   • actions/checkout@v2: Bước này sử dụng hành động actions/checkout để checkout mã nguồn từ repository.

   • Setup PHP: Bước này sử dụng hành động shivammathur/setup-php để cài đặt và cấu hình một môi trường PHP với phiên bản được chỉ định.

   • Laravel Setup: Bước này thực hiện cài đặt các gói PHP thông qua Composer.

   • Deploy: Bước này sử dụng hành động deployphp/action để triển khai ứng dụng. Nó sử dụng khóa riêng tư (private-key) và các biến môi trường (ssh-config) được lưu trữ trong Secrets của repository để thực hiện việc kết nối và triển khai ứng dụng lên máy chủ Staging (app.dev).

     • name: Đây là tên của bước, trong trường hợp này là "Deploy".

     • uses: Đây là hành động được sử dụng để thực hiện bước triển khai. Trong trường hợp này, hành động được sử dụng là deployphp/action@v1. Điều này cho biết rằng GitHub Action sẽ sử dụng phiên bản 1 của hành động deployphp/action.

     • with: Phần này chứa các tham số (options) được truyền cho hành động triển khai.

       • private-key: Đây là khóa riêng tư được sử dụng để xác thực khi kết nối với máy chủ từ xa. Giá trị của nó được lấy từ một secret có tên STG_PRIVATE_KEY. Secrets là một tính năng của GitHub Actions cho phép bạn lưu trữ các thông tin nhạy cảm mà bạn không muốn lộ ra ngoài như mật khẩu, khóa riêng tư, v.v.

       • dep: Đây là lệnh hoặc hành động cụ thể được sử dụng để thực hiện triển khai. Trong trường hợp này, đang sử dụng lệnh "deploy app.dev" , có thể là một lệnh do người dùng tự định nghĩa hoặc một lệnh đã được xây dựng sẵn. Lệnh này mình viết trong file deploy.php

       • ssh-config: Phần này chứa cấu hình SSH được sử dụng để kết nối với máy chủ từ xa. Nó cho biết tên máy chủ, địa chỉ IP hoặc tên miền (app.dev), tên người dùng (${{ secrets.STG_USER }}), và các cài đặt bổ sung như StrictHostKeyChecking no để vô hiệu hóa kiểm tra khóa máy chủ. Các giá trị của nó được lấy từ các secret như STG_HOST và STG_USER.

Cấu hình lại Nginx

Sau khi chúng ta đã hiểu và thiết lập xong toàn bộ các bước ở 2 bài, bây giờ chúng ta hãy thử push code lên nhánh mà chúng ta đã chỉ định để deploy trong workflow, sau khi nó deploy lên server nó sẽ tạo ra một folder mới chứa dự án của chúng ta như hình bên dưới.

1. Current: Thư mục current là một liên kết tượng trưng (symbolic link) đến thư mục release mới nhất mà Deployer đã triển khai. Khi bạn triển khai một phiên bản mới của ứng dụng, Deployer sẽ tạo một thư mục release mới và sau đó cập nhật liên kết current để trỏ đến thư mục release mới này. Thư mục current thường là nơi mà máy chủ web (như Nginx hoặc Apache) sẽ trỏ đến để phục vụ ứng dụng của bạn.

2. Releases: Thư mục releases chứa tất cả các phiên bản đã được triển khai của ứng dụng của bạn. Mỗi khi bạn triển khai một phiên bản mới, Deployer sẽ tạo một thư mục con mới trong releases và sao chép mã nguồn của ứng dụng vào đó. Điều này giúp bạn duy trì một lịch sử các phiên bản triển khai và cho phép bạn quay lại phiên bản trước đó nếu cần.

3. Dep: Thư mục dep chứa các tệp và thư mục liên quan đến việc triển khai của Deployer, bao gồm các script và công cụ liên quan đến quá trình triển khai.

4. Shared: Thư mục shared chứa các tệp và thư mục được chia sẻ giữa các phiên bản triển khai. Điều này bao gồm các tệp như cơ sở dữ liệu, tệp cấu hình, và các tệp lưu trữ dữ liệu không thay đổi giữa các phiên bản triển khai. Các tệp trong thư mục shared sẽ được liên kết hoặc sao chép vào thư mục current của phiên bản triển khai hiện tại mỗi khi một phiên bản mới được triển khai.

sudo systemctl restart nginx

Kiểm tra workfow trên giao diện Github

Các bạn vào repo dự án của các bạn trên Github, sau đó thì click vào Action để xem các workflows hoạt động.

Nếu thành cồng nó sẽ được hiện thị:

Còn nếu thất bài nó sẽ hiện thị:

Trong trường hợp này các bạn muốn xem tại sao lỗi thì nhấn vào xem chi tiết workflow đó và xem nguyên nhân lỗi và fix.

Tổng kết

Như vậy là xong tất cả các bước để triển khai 1 CI/CD cho dự án Laravel, mong rằng nó giúp ích cho dự án của các bạn.