Деплой в AWS S3 из GitHub Actions

Коротко: соберите артефакты в GitHub Actions, сохраните учетные данные AWS в GitHub Secrets и добавьте шаг deploy, использующий s3-sync или совместимый action. Это позволяет автоматически загружать билды в бакет S3 (или совместимое хранилище) для раздачи или хостинга статических сайтов.

Быстрые ссылки

• Почему стоит использовать AWS S3 для деплоя
• Как загружать в AWS S3 из GitHub Actions

Почему стоит использовать AWS S3 для деплоя

S3 — простое, надёжное и широко совместимое объектное хранилище. Оно подходит для раздачи статических сайтов, хранения артефактов сборки и интегрируется с IAM для тонкой настройки прав доступа. GitHub имеет собственное хранилище артефактов и GitHub Packages, но:

• GitHub artifacts предназначены для архивирования и тестов, истекают через 90 дней — не лучший выбор для постоянного продакшн-деплоя.
• GitHub Packages хорош для языковых пакетов (npm, Maven), но не заменяет объектное хранилище для произвольных файлов.

Если вы используете контейнерные образы, лучше хранить их в реестре контейнеров (например, GitHub Container Registry или Amazon ECR). Для остальных типов артефактов S3 остаётся универсальным выбором.

Важно: CI-решения и S3-совместимые сервисы (DigitalOcean Spaces, MinIO) используют одинаковый API, поэтому большинство инструкций применимы и к ним.

Перед началом — проверьте сборку

Перед добавлением шага загрузки убедитесь, что ваш workflow корректно собирает приложение и генерирует артефакты. Если одновременно править сборку и деплой, сложнее отлаживать причины сбоев.

Совет: сначала используйте встроённое действие upload-artifact для проверки содержимого директории локально в интерфейсе GitHub Actions.

Проверьте Summary > Artifacts, чтобы убедиться, что загружаемые файлы корректны.

Настройка секретов GitHub (AWS credentials)

Для доступа к S3 храните ключи в GitHub Secrets в разделе Settings → Secrets → Actions. Создайте, как минимум, эти секреты:

• AWS_ACCESS_KEY_ID — access key ID
• AWS_SECRET_ACCESS_KEY — secret access key
• AWS_S3_BUCKET — имя бакета
• AWS_REGION — регион (необязательно, по умолчанию us-east-1)

Важно: не храните ключи в репозитории, используйте Secrets. Ограничьте IAM-политику ключа до конкретного бакета и операций, необходимых для деплоя (PutObject, DeleteObject, ListBucket при необходимости).

Выбор action для загрузки в S3

Популярные варианты:

• jakejarvis/s3-sync-action — обёртка для aws cli/s3 sync, простая и надёжная.
• actions/aws-cli — универсальный aws cli для произвольных команд S3.
• stcalica/s3-upload — JavaScript-обёртка, кроссплатформенная (работает на Windows runners).
• s3cmd в кастомном шаге или контейнере — когда нужны опции s3cmd.

Примечание: многие action предполагают Linux-раннеры; если сборка идёт на Windows, выбирайте кроссплатформенные варианты.

Пример рабочего workflow

Ниже пример минимального GitHub Actions workflow, который собирает (эмулируется шаг build) и синхронизирует локальную директорию build/ в корень бакета S3. Подправьте пути и шаги под ваш проект.

name: CI

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build
        run: |
          echo "Здесь ваш билд-скрипт"
          mkdir -p build
          echo "index.html" > build/index.html

      - name: Upload build artifacts (debug)
        uses: actions/upload-artifact@v4
        with:
          name: site-build
          path: build/

      - name: Deploy to S3
        uses: jakejarvis/s3-sync-action@v0.5.1
        with:
          args: --acl public-read --follow-symlinks --delete
        env:
          AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: ${{ secrets.AWS_REGION }}
          SOURCE_DIR: 'build'  

Пояснения:

• args: можно передавать параметры, например –acl public-read чтобы объекты были общедоступны.
• –delete гарантирует, что в бакете не останутся старые файлы, не содержащиеся в текущем билде.
• SOURCE_DIR настраивает директорию для загрузки.

Когда это не сработает и альтернативы

• Если вы деплоите контейнеры, используйте реестр контейнеров (ECR, Docker Hub, GitHub CR).
• Для серверных приложений с конфигурацией и миграциями лучше применять CD-инструменты (Terraform, Ansible, AWS CodeDeploy).
• Для больших бинарных артефактов возможно имеет смысл использовать артефакт-репозиторий (Artifactory, Nexus).

Роли и чек-лист перед релизом

Разделение обязанностей помогает безопасному деплою.

Роль — DevOps инженер:

• Проверить IAM-политику для ключа (минимальные права).
• Настроить lifecycle политики S3 (если нужно хранить версии/устаревшие файлы).

Роль — Владелец репозитория:

• Создать и добавить Secrets в GitHub.
• Подтвердить, что public-read разрешён только для статических файлов, не содержащих секретов.

Чек-лист перед первым деплоем:

• Сборка проходит локально и в CI
• Артефакты проверены через upload-artifact
• Секреты добавлены в GitHub Secrets
• IAM-права минимальны
• Конфигурация action корректно указывает SOURCE_DIR и DEST_DIR

Отладка и логирование

Если деплой не прошёл, откройте лог шага Deploy to S3 — action обычно логирует команды s3 и ошибки. Типичные проблемы:

• Неправильные секреты: ошибка аутентификации.
• Отсутствие разрешений на PutObject/DeleteObject: ошибка доступа.
• Неправильный путь SOURCE_DIR: в бакет загружается пустая директория.

Критерии приёмки

• Файлы находятся в указанном бакете и видимы в консоли S3.
• Объекты имеют ожидаемые права чтения (если сайт должен быть публичным).
• Количество файлов и контрольные суммы соответствуют сборке.
• Время деплоя укладывается в требования (предсказуемость шага).

Мини-плейбук: восстановление и откат

Если в процессе деплоя что-то пошло не так:

1. Отключите распространение (если у вас CDN) или переключите трафик на предыдущую версию.
2. Восстановите файлы из предыдущей версии (если используете версионирование объектов) или переотправьте предыдущий артефакт.
3. Уточните причину в логах action и исправьте workflow.

Важно: прежде чем использовать опцию –delete, убедитесь, что в бакете нет ручных артефактов, которые не должны удаляться.

Безопасность и GDPR-заметки

• Не храните персональные данные в публичных бакетах.
• Контролируйте доступ через IAM и используйте шифрование (SSE) при необходимости.
• Для EU-пользователей выбирайте регион, соответствующий требованиям локального законодательства о хранении данных.

Советы по производительности и стоимости

• Для редких деплоев используйте простой sync. Для частых обновлений подумайте о CDN поверх S3 (CloudFront) для снижения задержек.
• Включите lifecycle-правила для автоматической архивации или удаления старых версий.

Быстрый контроль совместимости

• DigitalOcean Spaces и MinIO совместимы с API S3 — большинство action будут работать.
• Для приватных registries или альтернатив проверьте требования к аутентификации.

Факто-бокс

• Что требуется: рабочий workflow, GitHub Secrets с AWS-ключами, action для загрузки (s3-sync или альтернативы).
• Совместимость: Linux, macOS и Windows (с выбором подходящего action).

Краткое резюме

Использование S3 для деплоя из GitHub Actions даёт надёжный, гибкий и совместимый путь для размещения статических сайтов и артефактов. Ключевые шаги — убедиться в корректной сборке, безопасно хранить AWS-ключи в GitHub Secrets и выбрать подходящий action (с учётом платформы раннера). Проверьте логи шага deploy и настройте права доступа и lifecycle-политики для поддержания безопасности и порядка.

Важно: всегда тестируйте workflow в отдельной ветке или тестовом бакете, прежде чем менять продакшн-го бакет.