Українська
Робочий процес розгортання
Крок 1. Безперервне розгортання
Навіщо. Розгортання вручну – це перелік кроків: зібрати, скопіювати, виконати міграцію, перезапустити, перевірити. Коли це робиться раз на місяць, кожен крок – нагода помилитися: збирання з хибної гілки, забута міграція, перезапуск до завершення копіювання. Коли це робить робочий процес, ті самі кроки виконуються щоразу однаково, і розгортання стає досить дешевим, щоб робити його після кожної зміни. Невеликі й часті розгортання ще й безпечніші: коли щось ламається, причина в кількох останніх комітах.
Chatex розгортає кожну зміну main. Строго кажучи, це безперервна доставка (continuous delivery): кожну зміну зібрано, протестовано й готово, а кнопку натискає людина. Кнопка – це обов’язкове схвалення в GitHub (розділ Доступ для GitHub); приберіть її, і той самий робочий процес виконуватиме безперервне розгортання.
Робочий процес формують два принципи:
- Збирати один раз, розгортати ті самі байти. Реліз збирається й пакується в одному завданні та зберігається як артефакт; завдання розгортання лише копіює його. На сервері нічого не компілюється, тож серверу не потрібні ні SDK, ні Node.js, ні вихідний код.
- Сервер вирішує, чи реліз добрий. Після перемикання сервер перевіряє
/healthі сам повертається до попереднього релізу, якщо відповідь неHealthy(наступний розділ).
Крок 2. Файл робочого процесу
Що зробити. Створіть другий робочий процес поруч із ci.yml:
yaml
# Production deploy: CI, then package the API, the migration bundle and the web app,
# then (after approval on the "production" environment) copy them to the server and activate.
# Server setup and the required secrets are described in Docs/Deployment.md.
name: Deploy
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: production
cancel-in-progress: false
env:
DOTNET_NOLOGO: true
DOTNET_CLI_TELEMETRY_OPTOUT: true
jobs:
ci:
name: CI
uses: ./.github/workflows/ci.yml
package:
name: Package
needs: ci
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
with:
global-json-file: global.json
- name: Cache NuGet packages
uses: actions/cache@v6
with:
path: ~/.nuget/packages
key: nuget-${{ runner.os }}-${{ hashFiles('Directory.Packages.props', '**/*.csproj') }}
restore-keys: nuget-${{ runner.os }}-
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
cache-dependency-path: Source/Chatex.Web/package-lock.json
- name: Publish API
run: dotnet publish Source/Chatex.Api -c Release -r linux-x64 --self-contained false -o release/api
- name: Build migration bundle
run: |
dotnet tool restore
dotnet ef migrations bundle --project Source/Chatex.Data --configuration Release -r linux-x64 -o release/efbundle
- name: Build web app
working-directory: Source/Chatex.Web
run: |
npm ci
npm run build
cp -r dist/chatex/browser ../../release/web
- name: Add release metadata
run: |
echo "${{ github.sha }}" > release/REVISION
cp Deploy/activate-release.sh release/
- uses: actions/upload-artifact@v7
with:
name: chatex-release
path: release/
retention-days: 14
if-no-files-found: error
deploy:
name: Deploy
needs: package
runs-on: ubuntu-latest
timeout-minutes: 15
environment:
name: production
url: ${{ vars.PUBLIC_URL }}
env:
SSH_HOST: ${{ secrets.SSH_HOST }}
SSH_USER: ${{ secrets.SSH_USER }}
RELEASE: ${{ github.sha }}
steps:
- uses: actions/download-artifact@v8
with:
name: chatex-release
path: release
- name: Set up SSH
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
SSH_KNOWN_HOSTS: ${{ secrets.SSH_KNOWN_HOSTS }}
run: |
install -m 700 -d ~/.ssh
printf '%s\n' "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
host=$(printf '%s' "$SSH_HOST" | tr -d '[:space:]')
user=$(printf '%s' "$SSH_USER" | tr -d '[:space:]')
# Keep only "<type> <key>" from each line of SSH_KNOWN_HOSTS and pin it to SSH_HOST,
# so comments, Windows line endings or a different host name in the secret don't matter.
printf '%s\n' "$SSH_KNOWN_HOSTS" | tr -d '\r' \
| awk -v host="$host" '!/^[[:space:]]*(#|$)/ {
for (i = 1; i < NF; i++) if ($i ~ /^(ssh-|ecdsa-|sk-)/) { print host, $i, $(i + 1); break }
}' > ~/.ssh/known_hosts
if [ ! -s ~/.ssh/known_hosts ]; then
echo "::error::SSH_KNOWN_HOSTS contains no host key lines"
exit 1
fi
# Fingerprints are public; print both sides so a mismatch is visible in the log.
echo "Pinned host keys:"
ssh-keygen -lf ~/.ssh/known_hosts | awk '{ print " " $2, $NF }'
echo "Keys the server offers:"
ssh-keyscan -T 10 "$host" 2>/dev/null | ssh-keygen -lf - | awk '{ print " " $2, $NF }'
printf 'Host deploy-target\n HostName %s\n User %s\n IdentityFile ~/.ssh/deploy_key\n IdentitiesOnly yes\n StrictHostKeyChecking yes\n' \
"$host" "$user" > ~/.ssh/config
# Uploads go to incoming/; chatex-activate moves them into releases/.
- name: Upload release
run: rsync -rltz --delete --chmod=Du=rwx,Dgo=rx,Fu=rw,Fgo=r release/ "deploy-target:/opt/chatex/incoming/$RELEASE/"
- name: Activate release
run: |
# RELEASE is meant to expand on the runner.
# shellcheck disable=SC2029
ssh deploy-target sudo /usr/local/bin/chatex-activate "$RELEASE"
- name: Smoke test
env:
PUBLIC_URL: ${{ vars.PUBLIC_URL }}
run: curl --fail --silent --show-error --retry 10 --retry-delay 3 --retry-all-errors "$PUBLIC_URL/health"Робочий процес має три завдання, що йдуть одне за одним, бо кожне має needs попереднього: ci → package → deploy. Решта цього розділу охоплює перші два; завдання розгортання йде в розділі Доступ для GitHub, після серверної частини, з якою воно взаємодіє.
Крок 3. Тригери й паралельність
yaml
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: production
cancel-in-progress: falsepushдоmain– кожен злитий запит на злиття розгортається. Разом із набором правил із теми 22 доmainпотрапляє лише перевірений код.workflow_dispatchдодає кнопку Run workflow на сторінці Actions, щоб знову розгорнути поточнийmainбез нового коміту – наприклад, після зміни секрету.permissions: contents: read– завданням не потрібно нічого, крім читання репозиторію. Права на сервер походять із секретів, а не з токена.concurrency: group: productionзcancel-in-progress: false– одночасно працює щонайбільше один запуск групи; новіший запуск чекає, а не скасовує поточний. Скасування розгортання між «міграцією» і «перемиканням» залишило б сервер у стані, який ніхто не тестував. (Якщо чекає кілька запусків, GitHub лишає тільки найновіший, що нам і потрібно: він містить усі зміни.)
Крок 4. Повторне використання CI
yaml
ci:
name: CI
uses: ./.github/workflows/ci.ymlЗавдання з uses: замість runs-on: викликає повторно використовуваний робочий процес – це можливо, бо ci.yml оголошує подію workflow_call (тема 22). Обидва завдання CI знову виконуються на коміті main, і розгортання триває, лише якщо обидва зелені. Навіщо ще раз перевіряти те, що вже перевірив запит на злиття? Бо main після злиття – це новий коміт: два запити на злиття, зелені самі по собі, можуть зламати один одного, коли обидва злито. До того ж той самий файл обслуговує обидва робочі процеси, тож є лише одне визначення «перевіреного».
На сторінці запуску завдання з’являються як CI / Backend і CI / Frontend.
Крок 5. Завдання пакування
Навіщо. Серверу потрібні чотири речі й більше нічого: API, готове до запуску, спосіб застосувати міграції без SDK, статичні файли клієнта й примітка, з якого коміту все це походить. Завдання пакування створює їх у папці release/ і зберігає її як артефакт.
Що зробити. Завдання без кроків налаштування, які такі самі, як у CI:
yaml
package:
name: Package
needs: ci
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
# ...
- name: Publish API
run: dotnet publish Source/Chatex.Api -c Release -r linux-x64 --self-contained false -o release/api
- name: Build migration bundle
run: |
dotnet tool restore
dotnet ef migrations bundle --project Source/Chatex.Data --configuration Release -r linux-x64 -o release/efbundle
- name: Build web app
working-directory: Source/Chatex.Web
run: |
npm ci
npm run build
cp -r dist/chatex/browser ../../release/web
- name: Add release metadata
run: |
echo "${{ github.sha }}" > release/REVISION
cp Deploy/activate-release.sh release/
- uses: actions/upload-artifact@v7
with:
name: chatex-release
path: release/
retention-days: 14
if-no-files-found: errordotnet publish … -r linux-x64 --self-contained false -o release/api– API з усіма бібліотеками, скомпільоване в Release для 64-бітного Linux, уrelease/api. Залежна від середовища публікація (framework-dependent,--self-contained false): середовище виконання .NET не включено, бо сервер має його з пакета Ubuntuaspnetcore-runtime-10.0і звідти ж отримує його оновлення безпеки. Автономна публікація несла б усе середовище виконання, на десятки мегабайтів більше, і заморожувала б його версію до наступного розгортання.dotnet ef migrations bundle … -o release/efbundle– пакет міграцій, анонсований у темі 4: один виконуваний файл Linux, що містить кожну міграціюChatex.Dataі застосовує відсутні до бази даних, указаної в--connection. Серверу не потрібні ні SDK, ніdotnet-ef, ні вихідний код.--configuration Release(записано повністю: уdotnet ef-cозначає--context) збирає проєкт даних у Release.npm ci,npm run build,cp -r dist/chatex/browser ../../release/web– збирання клієнта для production, папка, яку Nginx віддає якcurrent/web.REVISION– повний хеш коміту. Вираз у подвійних фігурних дужках GitHub замінює до запуску оболонки; на серверіcat /opt/chatex/current/REVISIONточно каже, який коміт зараз працює.cp Deploy/activate-release.sh release/– копія скрипта активації, що належить до цього релізу, для довідки. Сервер запускає свою встановлену копію в/usr/local/bin(наступний розділ); зміну скрипта в репозиторії треба також вручну встановити на сервері.upload-artifactзберігаєrelease/як артефакт chatex-release запуску на 14 днів.if-no-files-found: errorпровалює завдання, якщо папки немає, замість того щоб розгорнути нічого.
Чому не збирати на сервері?
Збирання на сервері – класичний ярлик: git pull && dotnet publish && npm run build у сеансі SSH. Воно потребує SDK і Node.js на робочій машині, гігабайтів кешів збирання поруч із живими даними, хвилин високого навантаження процесора, поки користувачі спілкуються, і розгортає те, що встигло скомпілюватися там, – а не те, що тестував CI. Артефакт уникає всіх чотирьох проблем.
Крок 6. Збирання релізу локально
Навіщо. Перш ніж робочий процес запрацює на GitHub, варто один раз побачити реліз на власні очі – а вміння зібрати його знадобиться, коли GitHub недоступний (див. «Розгортання вручну» в розділі Розгортання та експлуатація).
Що зробити. З кореня репозиторію виконайте команди завдання пакування:
powershell
dotnet publish Source/Chatex.Api -c Release -r linux-x64 --self-contained false -o release/apipowershell
dotnet tool restorepowershell
dotnet ef migrations bundle --project Source/Chatex.Data --configuration Release -r linux-x64 -o release/efbundleКрок пакета завершується рядком Done. Migrations Bundle: …\release\efbundle.
Перевірка
powershell
Get-ChildItem releaseПапка містить api і файл efbundle (близько 34 МБ). release/api містить Chatex.Api.dll, бібліотеки й appsettings.Production.json – разом приблизно 12 МБ. Папку release/ Git ігнорує (.gitignore із теми 2 містить [Rr]elease/), тож git status лишається чистим. Видаліть її, коли роздивитеся:
powershell
Remove-Item -Recurse releaseЗакомітьте робочий процес і надішліть його до dev:
powershell
git add .githubpowershell
git commit -m "Add the deploy workflow"powershell
git pushПоки що нічого не розгортається: робочий процес запускається на main, а сервер не готовий приймати реліз, доки не виконано два наступні розділи.