Envoy

업데이트됨

번역일: 2026년 9월 17일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 9월 17일
번역 갱신: 2026년 9월 17일

Envoy

소개
설치
태스크 작성하기
태스크 실행하기
- 태스크 실행 확인받기
알림

소개

Laravel Envoy는 원격 서버에서 반복적으로 실행하는 작업들을 손쉽게 처리할 수 있게 해주는 도구입니다. Blade와 유사한 문법을 사용해 배포 작업, Artisan 명령어 실행 등의 태스크를 간단하게 정의할 수 있습니다. 현재 Envoy는 macOS와 Linux 환경만 공식 지원합니다. Windows에서는 WSL2를 사용하면 문제없이 활용할 수 있습니다.

설치

먼저 Composer를 통해 프로젝트에 Envoy를 설치합니다:

composer require laravel/envoy --dev

설치가 완료되면 애플리케이션의 vendor/bin 디렉터리에 Envoy 실행 파일이 생성됩니다:

php vendor/bin/envoy

태스크 작성하기

태스크 정의하기

태스크(Task)는 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 파일을 가져와서 그 파일에 정의된 스토리와 태스크를 현재 파일에 추가할 수 있습니다. 파일을 가져온 이후에는 마치 자신의 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

경우에 따라 Envoy 태스크를 실행하기 전에 임의의 PHP 코드를 먼저 실행해야 할 때가 있습니다. 이럴 땐 @setup 디렉티브를 사용해서 태스크 실행 전에 수행할 PHP 코드 블록을 정의할 수 있습니다:

@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의 "echo" 문법을 사용해 이 옵션 값에 접근할 수 있습니다. 또한 태스크 안에서 Blade의 if 문이나 반복문도 사용할 수 있습니다. 예를 들어, git pull 명령어를 실행하기 전에 $branch 변수가 존재하는지 확인해봅시다:

@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

스토리

스토리(Story)는 여러 개의 태스크를 하나의 편리한 이름으로 묶어주는 기능입니다. 예를 들어, 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

훅

태스크와 스토리가 실행되는 동안 여러 개의 훅(Hook)이 함께 실행됩니다. Envoy가 지원하는 훅의 종류로는 @before, @after, @error, @success, @finished가 있습니다. 이 훅들에 작성한 코드는 모두 PHP 코드로 해석되며, 태스크가 실행되는 원격 서버가 아니라 로컬 환경에서 실행된다는 점에 유의해야 합니다.

각 훅은 원하는 만큼 여러 번 정의할 수 있으며, Envoy 스크립트에 작성된 순서대로 실행됩니다.

`@before`

각 태스크가 실행되기 전에, Envoy 스크립트에 등록된 모든 @before 훅이 실행됩니다. @before 훅은 실행될 태스크의 이름을 인자로 전달받습니다:

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

`@after`

각 태스크가 실행된 후에, Envoy 스크립트에 등록된 모든 @after 훅이 실행됩니다. @after 훅은 실행된 태스크의 이름을 인자로 전달받습니다:

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

`@error`

태스크가 실패할 때마다(종료 코드가 0보다 클 때) Envoy 스크립트에 등록된 모든 @error 훅이 실행됩니다. @error 훅은 실행된 태스크의 이름을 인자로 전달받습니다:

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

`@success`

모든 태스크가 에러 없이 실행되면, Envoy 스크립트에 등록된 모든 @success 훅이 실행됩니다:

@success
    // ...
@endsuccess

`@finished`

모든 태스크의 실행이 끝나면(종료 상태와 무관하게) @finished 훅이 실행됩니다. @finished 훅은 완료된 태스크의 종료 코드를 인자로 전달받으며, 이 값은 null이거나 0 이상의 정수입니다:

@finished
    if ($exitCode > 0) {
        // 태스크 중 하나에서 오류가 발생한 경우...
    }
@endfinished

태스크 실행하기

애플리케이션의 Envoy.blade.php 파일에 정의된 태스크나 스토리를 실행하려면, run 명령어에 실행할 태스크(또는 스토리)의 이름을 전달하면 됩니다. Envoy는 태스크를 실행하면서 원격 서버로부터 전달받는 출력 결과를 실시간으로 화면에 보여줍니다:

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" 연동을 생성하여 발급받을 수 있습니다.

@slack 디렉티브의 첫 번째 인자로는 전체 웹훅 URL을 전달해야 합니다. 두 번째 인자로는 채널명(#channel) 또는 사용자명(@user)을 전달합니다:

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

기본적으로 Envoy는 실행된 태스크에 대한 설명 메시지를 알림 채널로 전송합니다. 하지만 @slack 디렉티브에 세 번째 인자를 전달하면 원하는 메시지로 덮어쓸 수 있습니다:

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

Discord

Envoy는 태스크 실행 후 Discord로도 알림을 보낼 수 있습니다. @discord 디렉티브는 Discord 웹훅 URL과 메시지를 인자로 받습니다. 웹훅 URL은 Discord 서버 설정에서 "Webhook"을 생성하고 알림을 게시할 채널을 지정하면 발급받을 수 있습니다. 발급받은 전체 웹훅 URL을 @discord 디렉티브에 전달하세요:

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

Envoy는 태스크 실행 후 Telegram으로도 알림을 보낼 수 있습니다. @telegram 디렉티브는 Telegram 봇 ID와 채팅 ID를 인자로 받습니다. 봇 ID는 BotFather를 통해 새 봇을 만들면 발급받을 수 있고, 채팅 ID는 @username_to_id_bot을 이용해 확인할 수 있습니다. 발급받은 봇 ID와 채팅 ID를 @telegram 디렉티브에 전달하세요:

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

Microsoft Teams

Envoy는 태스크 실행 후 Microsoft Teams로도 알림을 보낼 수 있습니다. @microsoftTeams 디렉티브는 Teams 웹훅(필수), 메시지, 테마 색상(success, info, warning, error), 그리고 추가 옵션 배열을 인자로 받습니다. Teams 웹훅은 incoming webhook 문서를 참고하여 생성할 수 있습니다. Teams API는 이 외에도 제목, 요약, 섹션 등 메시지 박스를 꾸밀 수 있는 다양한 속성을 제공하며, 자세한 내용은 Microsoft Teams 공식 문서에서 확인할 수 있습니다. 발급받은 전체 웹훅 URL을 @microsoftTeams 디렉티브에 전달하세요:

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