Laravel Envoy

번역일: 2026년 6월 20일

Laravel Envoy

소개
설치
태스크 작성
- 태스크 정의
- 다중 서버
- Setup
- 변수
- 스토리
- 훅
태스크 실행
- 실행 전 확인
알림

소개

Laravel Envoy는 원격 서버에서 반복적으로 실행하는 작업을 자동화하는 도구입니다. Blade 스타일의 문법을 사용해 배포, Artisan 명령 실행 등의 태스크를 간결하게 정의할 수 있습니다. 현재 Envoy는 Mac과 Linux 운영체제를 지원하며, Windows에서는 WSL2를 통해 사용할 수 있습니다.

설치

Composer로 프로젝트에 Envoy를 설치합니다:

composer require laravel/envoy --dev

설치가 완료되면 vendor/bin 디렉터리에서 Envoy 바이너리를 실행할 수 있습니다:

php vendor/bin/envoy

태스크 작성

태스크 정의

태스크는 Envoy의 기본 실행 단위입니다. 각 태스크에는 원격 서버에서 실행할 셸 명령을 정의합니다. 예를 들어 큐 워커 서버에서 php artisan queue:restart를 실행하는 태스크를 만들 수 있습니다.

모든 Envoy 태스크는 프로젝트 루트의 Envoy.blade.php 파일에 정의합니다. 아래는 기본 예시입니다:

@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])

@task('restart-queues', ['on' => 'workers'])
    cd /home/user/example.com
    php artisan queue:restart
@endtask

파일 상단의 @servers에 서버 목록을 정의하고, 각 태스크의 on 옵션에서 해당 서버를 참조합니다. @servers 선언은 반드시 한 줄로 작성해야 합니다. @task 블록 안에는 서버에서 실행할 셸 명령을 작성합니다.

로컬 태스크

서버 IP를 127.0.0.1로 지정하면 해당 태스크를 로컬 머신에서 실행할 수 있습니다:

@servers(['localhost' => '127.0.0.1'])

Envoy 태스크 가져오기

@import 디렉티브를 사용하면 다른 Envoy 파일의 태스크와 스토리를 현재 파일로 불러올 수 있습니다. 가져온 태스크는 마치 현재 파일에 직접 정의한 것처럼 실행할 수 있습니다:

@import('vendor/package/Envoy.blade.php')

다중 서버

Envoy를 사용하면 여러 서버에 걸쳐 태스크를 손쉽게 실행할 수 있습니다. @servers 선언에 서버를 추가하고 각각 고유한 이름을 부여한 뒤, 태스크의 on 배열에 대상 서버를 나열하면 됩니다:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2']])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask

병렬 실행

기본적으로 태스크는 서버마다 순차적으로 실행됩니다. 즉, 첫 번째 서버에서 태스크가 완료된 후 두 번째 서버로 넘어갑니다. 여러 서버에서 동시에 실행하려면 태스크 선언에 parallel 옵션을 추가하세요:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask

Setup

태스크 실행 전에 PHP 코드를 미리 실행해야 할 경우, @setup 디렉티브를 사용합니다. 여기서 정의한 변수는 이후 태스크에서 참조할 수 있습니다:

@setup
    $now = new DateTime;
@endsetup

태스크 실행 전에 외부 PHP 파일을 불러와야 한다면 Envoy.blade.php 파일 상단에서 @include 디렉티브를 사용하세요:

@include('vendor/autoload.php')

@task('restart-queues')
    # ...
@endtask

변수

Envoy를 실행할 때 명령줄에서 인수를 전달하면 태스크 내부에서 해당 값을 사용할 수 있습니다:

php vendor/bin/envoy run deploy --branch=master

태스크 안에서는 Blade의 {{ }} 출력 문법뿐 아니라 @if, @foreach 등의 제어문도 사용할 수 있습니다. 아래 예시는 $branch 변수가 존재하는 경우에만 git pull을 실행합니다:

@servers(['web' => ['user@192.168.1.1']])

@task('deploy', ['on' => 'web'])
    cd /home/user/example.com

    @if ($branch)
        git pull origin {{ $branch }}
    @endif

    php artisan migrate --force
@endtask

스토리

스토리는 여러 태스크를 하나의 이름으로 묶어 순서대로 실행하는 기능입니다. 예를 들어 deploy 스토리 안에 update-code와 install-dependencies 태스크를 나열하면, 두 태스크가 순차적으로 실행됩니다:

@servers(['web' => ['user@192.168.1.1']])

@story('deploy')
    update-code
    install-dependencies
@endstory

@task('update-code')
    cd /home/user/example.com
    git pull origin master
@endtask

@task('install-dependencies')
    cd /home/user/example.com
    composer install
@endtask

스토리는 태스크와 동일한 방식으로 실행합니다:

php vendor/bin/envoy run deploy

NOTE

스토리는 태스크를 묶는 단순한 그룹입니다. 각 태스크는 여전히 독립적으로도 실행할 수 있습니다.

훅

Envoy는 태스크와 스토리 실행 흐름의 특정 시점에 훅을 실행할 수 있습니다. 지원하는 훅의 종류는 @before, @after, @error, @success, @finished입니다. 훅 안의 코드는 PHP로 해석되며, 원격 서버가 아닌 로컬 머신에서 실행됩니다.

각 훅은 여러 번 정의할 수 있으며, Envoy.blade.php 파일에 나타나는 순서대로 실행됩니다.

`@before`

각 태스크가 실행되기 전에 호출됩니다. 실행될 태스크의 이름을 $task 변수로 받습니다:

@before
    if ($task === 'deploy') {
        // ...
    }
@endbefore

`@after`

각 태스크가 실행된 후에 호출됩니다. 실행된 태스크의 이름을 $task 변수로 받습니다:

@after
    if ($task === 'deploy') {
        // ...
    }
@endafter

`@error`

태스크가 실패한 경우(종료 코드가 0보다 큰 경우) 호출됩니다. 실패한 태스크의 이름을 $task 변수로 받습니다:

@error
    if ($task === 'deploy') {
        // ...
    }
@enderror

`@success`

모든 태스크가 오류 없이 완료된 경우에 호출됩니다:

@success
    // ...
@endsuccess

`@finished`

모든 태스크 실행이 끝난 후 성공 여부와 관계없이 항상 호출됩니다. $exitCode 변수로 종료 코드를 받으며, null이거나 0 이상의 정수입니다:

@finished
    if ($exitCode > 0) {
        // 태스크 중 하나 이상에서 오류가 발생했습니다.
    }
@endfinished

아래는 훅의 실행 흐름을 나타낸 다이어그램입니다:

태스크 실행

Envoy.blade.php에 정의한 태스크나 스토리를 실행하려면 run 명령에 이름을 전달합니다. 실행 중에는 원격 서버의 출력이 실시간으로 표시됩니다:

php vendor/bin/envoy run deploy

실행 전 확인

데이터베이스 마이그레이션이나 캐시 초기화처럼 되돌리기 어려운 작업을 실행하기 전에 확인 프롬프트를 띄우고 싶다면, 태스크 선언에 confirm 옵션을 추가하세요:

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

알림

Slack

Envoy는 태스크 실행 후 Slack으로 알림을 보낼 수 있습니다. @slack 디렉티브에는 Slack 웹훅 URL과 채널/사용자 이름을 전달합니다. 웹훅 URL은 Slack 관리 패널에서 "Incoming WebHooks" 연동을 생성하면 발급받을 수 있습니다.

첫 번째 인수로 전체 웹훅 URL, 두 번째 인수로 채널명(#channel) 또는 사용자명(@user)을 전달하세요:

@finished
    @slack('webhook-url', '#bots')
@endfinished

기본적으로 실행된 태스크 정보가 담긴 메시지가 전송됩니다. 세 번째 인수로 커스텀 메시지를 지정할 수도 있습니다:

@finished
    @slack('webhook-url', '#bots', '배포가 완료되었습니다.')
@endfinished

Discord

Envoy는 태스크 실행 후 Discord로도 알림을 보낼 수 있습니다. @discord 디렉티브에 Discord 웹훅 URL을 전달합니다. 웹훅 URL은 서버 설정에서 "Webhook"을 생성하고 알림을 받을 채널을 선택하면 발급받을 수 있습니다:

@finished
    @discord('discord-webhook-url')
@endfinished

Envoy는 태스크 실행 후 Telegram으로도 알림을 보낼 수 있습니다. @telegram 디렉티브에는 Telegram Bot ID와 Chat ID를 전달합니다. Bot ID는 BotFather로 봇을 생성하면 받을 수 있으며, Chat ID는 @username_to_id_bot으로 확인할 수 있습니다:

@finished
    @telegram('bot-id','chat-id')
@endfinished

Microsoft Teams

Envoy는 태스크 실행 후 Microsoft Teams로도 알림을 보낼 수 있습니다. @microsoftTeams 디렉티브에는 Teams 웹훅 URL(필수), 메시지, 테마 색상(success, info, warning, error), 그리고 옵션 배열을 전달할 수 있습니다. Teams 웹훅 URL은 incoming webhook 설정에서 발급받을 수 있습니다. 제목, 요약, 섹션 등 다양한 메시지 커스터마이징 옵션은 Microsoft Teams 공식 문서를 참고하세요:

@finished
    @microsoftTeams('webhook-url')
@endfinished