github pages deploy action
v4.7.2
Автоматически разверните свой проект на страницы GitHub с действиями GitHub. Это действие может быть настроено, чтобы подтолкнуть ваш готовый к производству код в любую филиал, который вы хотите, включая GH-страницы и документы . Он также может обрабатывать развертывание репозиторий и работает с Github Enterprise.
Техническое обслуживание этого проекта стало возможным для всех участников и спонсоров. Если вы хотите спонсировать этот проект, и ваш логотип аватара или компании появится ниже, нажмите здесь. ?
Вы можете включить действие в свой рабочий процесс, чтобы вызвать любое событие, которое поддерживает действия Github. Если удаленная филиал, которую вы хотите развернуть, еще не существует, действие создаст его для вас. Ваш рабочий процесс также должен включить шаг actions/checkout прежде чем этот рабочий процесс запустится, чтобы развертывание работало. Если вы намереваетесь сделать несколько развертываний в быстрой последовательности, вам может потребоваться использовать параметр параллелизма в вашем рабочем процессе, чтобы предотвратить совпадения.
Вы можете просмотреть пример этого ниже.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build-and-deploy :
concurrency : ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build # The folder the action should deploy. Примечание
Вы должны настроить свой репозиторий для развертывания из филиала, к которой вы настаиваете. Для этого перейдите в настройки репозитория, нажмите на Pages и выберите Deploy from a Branch из раскрывающегося списка Source . Оттуда выберите филиал, который вы предоставили в действие. В большинстве случаев это будет gh-pages , так как это по умолчанию.
Если вы хотите сделать это, так что рабочий процесс только запускает события Push до определенных ветвей, то вы можете изменить раздел on .
on :
push :
branches :
- main Предупреждение
Если вы не предоставите действие с помощью токена доступа или ключа SSH, вы должны получить доступ к настройкам репозиториев и предоставить Read and Write Permissions для предоставленного GITHUB_TOKEN , в противном случае вы потенциально столкнетесь с проблемами разрешения. В качестве альтернативы вы можете установить следующее в своем файле рабочего процесса, чтобы предоставить действию необходимые ему разрешения.
permissions :
contents : write with частью рабочего процесса должен быть настроен до того, как действие будет сработать. Вы можете добавить их в with найденный в примерах выше. На любые secrets должны ссылаться с использованием синтаксиса кронштейна и храниться в меню Settings/Secrets репозитория GitHub. Вы можете узнать больше о установке переменных среды с помощью действий GitHub здесь.
Следующие параметры должны быть настроены, чтобы сделать развертывание.
| Ключ | Ценность информации | Тип | Необходимый |
|---|---|---|---|
folder | Папка в вашем репозитории, которую вы хотите развернуть. Если ваш сценарий сборки собирает в каталог под названием build , вы бы поместили его здесь. Если вы хотите развернуть корневой каталог, вы можете разместить . здесь. Вы также можете использовать абсолютные пути файла, поспешивая ~ к пути папки. Обратите внимание, что любые файлы/папки, сопоставляющие .gitignore , не будут развернуты. Некоторые инструменты автоматически генерируют файл .gitignore для вывода сборки. | with | Да |
По умолчанию действие не нуждается в конфигурации токена, и использует предоставленный токен Github с примером репозитория, чтобы сделать развертывание. Если вам требуется больше настройки, вы можете изменить тип развертывания, используя следующие параметры.
| Ключ | Ценность информации | Тип | Необходимый |
|---|---|---|---|
token | Этот вариант по умолчанию по умолчанию в токен Github с высоте. Однако, если вам нужно больше разрешений для таких вещей, как развертывание в другой репозиторий, вы можете добавить здесь личный токен доступа (PAT). Это должно храниться в secrets / with меню в секрете . Мы рекомендуем использовать сервисную учетную запись с наименьшими разрешениями, необходимыми, и рекомендуем при генерации нового PAT, который вы выбираете наименьшие необходимые сферы разрешения. Узнайте больше о создании и использовании зашифрованных секретов здесь. | with | Нет |
ssh-key | Вы можете настроить действие для развертывания с помощью SSH, установив эту опцию на частный ключ SSH, хранящийся в секрете . Также можно настроить на true , чтобы использовать существующую конфигурацию клиента SSH. Для получения более подробной информации о том, как добавить вашу публичную/частную пару клавиш SSH, обратитесь к разделу «Использование ключа развертывания этого чтения». | with | Нет |
| Ключ | Ценность информации | Тип | Необходимый |
|---|---|---|---|
branch | Это филиал, который вы хотите развернуть, например, gh-pages или docs . По умолчанию к gh-pages . | with | Нет |
git-config-name | Позволяет настроить имя, которое прикреплено к конфигурации GIT, которое используется при нажатии коммита с развертыванием. Если это не включено, он будет использовать имя в контексте GitHub, за которым следует имя действия. | with | Нет |
git-config-email | Позволяет настроить электронное письмо, прикрепленное к конфигурации GIT, которая используется при нажатии коммита с развертыванием. Если это не включено, он будет использовать электронную почту в контексте GitHub, за которым следует общая электронная почта noreply github. Вы можете включить <> для значения, если вы хотите вообще опустить это поле и протолкнуть коммиты без электронной почты. | with | Нет |
repository-name | Позволяет вам указать другой путь репозитория, если у вас есть разрешения на то, чтобы подтолкнуть к нему. Это должно быть отформатировано так: JamesIves/github-pages-deploy-action . Вам нужно будет использовать PAT в входе token для этой параметры конфигурации для правильной работы. | with | Нет |
target-folder | Если вы хотите протолкнуть содержимое папки развертывания в конкретный каталог в отделении развертывания, вы можете указать его здесь. | with | Нет |
commit-message | Если вам нужно настроить сообщение о коммите для интеграции, вы можете это сделать. | with | Нет |
clean | Вы можете использовать эту опцию для удаления файлов из пункта назначения развертывания, которые больше не существуют в вашем источнике развертывания. Одним из вариантов использования является то, что ваш проект генерирует хэшированные файлы, которые варьируются от сборки к сборке. Использование clean не повлияет на каталоги .git , .github или .ssh . Эта опция включается по умолчанию и может быть переключен, установив его на false . | with | Нет |
clean-exclude | Если вам нужно использовать clean , но вы хотите сохранить определенные файлы или папки, вы можете использовать эту опцию. Это должно содержать каждую шаблон в виде одной линии в многослойной строке. | with | Нет |
dry-run | На самом деле не толкайте, но используйте --dry-run на git push вызовах. | with | Нет |
single-commit | Этот вариант может быть переключен на true , если вы предпочитаете иметь единый коммит в отделении развертывания вместо того, чтобы поддерживать полную историю. Использование этой опции также приведет к уничтожению любой существующей истории из отделения развертывания . | with | Нет |
force | Force-Push Новые развертывания, чтобы перезаписать предыдущую версию; В противном случае, попытаться переиграть новые развертывания на любые существующие. Эта опция включается по умолчанию и может быть переключена, установив его на false , что может быть полезно, если в одной ветви есть несколько развертываний. | with | Нет |
attempt-limit | Сколько попыток Rebase пытается сделать, прежде чем приостановить работу. Этот вариант по умолчанию по умолчанию 3 и может быть полезна для увеличения, когда существует несколько развертываний в одной ветви. | with | Нет |
silent | Замолчать выход действия, предотвращая его отображение сообщений GIT. | with | Нет |
tag | Добавьте тег в коммит. Работает только тогда, когда dry-run не используется. | with | Нет |
При правильном настроенном действии вы должны увидеть запуск рабочего процесса развертывание в настроенных условиях.
Действие будет экспортировать переменную среды, которая называется deployment_status , которую вы можете использовать в своем рабочем процессе, чтобы определить, было ли развертывание успешным или нет. Вы можете найти объяснение каждого типа статуса ниже.
| Статус | Описание |
|---|---|
success | Статус success указывает на то, что действие смогло успешно развернуться в филиале. |
failed | failed статус указывает, что действие столкнулось с ошибкой при попытке развернуть. |
skipped | skipped статус указывает на то, что действие вышло рано, так как не было ничего нового для развертывания. |
Это значение также устанавливается как шаг вывод в качестве deployment-status .
Если вы предпочитаете использовать ключ развертывания SSH, в отличие от токена, вы должны сначала сгенерировать новую клавишу SSH, выполнив следующую команду терминала, заменив электронное письмо с помощью одной, подключенной к вашей учетной записи Github.
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " " После того, как вы сгенерировали пару клавиш, вы должны добавить содержимое открытого ключа в меню «Развертывание клавиш вашего репозитория». Вы можете найти эту опцию, перейдя в Settings > Deploy Keys , вы можете назвать открытый ключ, что угодно, но вам нужно дать ему доступ на записи. После этого добавьте содержимое закрытого ключа в меню Settings > Secrets в качестве DEPLOY_KEY .
С помощью этого вы можете установить часть ssh-key для вашего частного ключа, хранящегося в секрете.
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : site
ssh-key : ${{ secrets.DEPLOY_KEY }} name : Build and Deploy
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txt
ssh-key : ${{ secrets.DEPLOY_KEY }} В качестве альтернативы, если вы уже настроили клиент SSH в течение предыдущего шага, вы можете true опцию ssh-key , чтобы позволить ему развернуться с помощью существующего клиента SSH. Вместо настройки конфигурации клиента она просто переключится на использование конечных точек Github SSH.
Это действие в основном разработано с использованием Ubuntu. В вашей конфигурации работы рабочего процесса рекомендуется установить свойство runs-on на ubuntu-latest .
jobs :
build-and-deploy :
runs-on : ubuntu-latest Если вы используете операционную систему, такую как Windows, вы можете облегчить это с помощью артефактов. В вашей конфигурации рабочего процесса вы можете использовать actions/upload-artifact и actions/download-artifact для перемещения вашего проекта, созданного на работе Windows, на вторичную задание, которое будет обрабатывать развертывание.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build :
runs-on : windows-latest # The first job utilizes windows-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Upload Artifacts ? # The project is then uploaded as an artifact named 'site'.
uses : actions/upload-artifact@v1
with :
name : site
path : build
deploy :
concurrency : ci-${{ github.ref }}
needs : [build] # The second job must depend on the first one to complete before running and uses ubuntu-latest instead of windows.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Download Artifacts ? # The built project is downloaded into the 'site' folder.
uses : actions/download-artifact@v1
with :
name : site
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : ' site ' # The deployment folder should match the name of the artifact. Even though our project builds into the 'build' folder the artifact name of 'site' must be placed here. Если вы используете контейнер в своем рабочем процессе, вам может потребоваться запустить дополнительный шаг для установки rsync , поскольку от этого зависит это действие. Вы можете просмотреть пример этого ниже.
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4 Если вы используете пользовательский домен и требуете файла CNAME , или если вам требуется использование файла .nojekyll , вы можете безопасно совершить эти файлы непосредственно в ветвь развертывания без переоценки после каждого развертывания, кроме того, вы можете включить эти файлы в папку развертывания, чтобы обновить их. Если вам нужно добавить дополнительные файлы в развертывание, которое следует игнорировать с помощью этапов очистки сборки, вы можете использовать опцию clean-exclude .
name : Build and Deploy
permissions :
contents : write
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txtЕсли вы хотите удалить эти файлы, вы должны перейти в ветвь развертывания напрямую, чтобы удалить их. Это предотвращение случайных изменений в вашем сценарии развертывания в создании нарушающих изменений.
