github pages deploy action
v4.7.2
GitHubアクションを使用して、プロジェクトをGitHubページに自動的に展開します。このアクションは、GH-PageやDocsを含む、生産対応コードを希望する任意のブランチにプッシュするように構成できます。また、クロスリポジトリの展開を処理し、GitHub Enterpriseとも連絡することもできます。
このプロジェクトのメンテナンスは、すべての貢献者とスポンサーによって可能になります。このプロジェクトを後援し、アバターまたは会社のロゴを以下に表示したい場合は、ここをクリックしてください。 ？
GitHub Actionsがサポートするイベントをトリガーするために、ワークフローにアクションを含めることができます。展開したいリモートブランチがまだ存在しない場合、アクションはあなたのためにそれを作成します。展開が機能するために、このワークフローが実行される前に、ワークフローも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をクリックして、 SourceドロップダウンからDeploy from a Branch選択します。そこから、アクションに提供したブランチを選択します。ほとんどの場合、これはデフォルトであるため、これはgh-pagesになります。
ワークフローが特定のブランチへのプッシュイベントのみをトリガーするようにしたい場合は、 onセクションを変更できます。
on :
push :
branches :
- main 警告
アクセストークンまたはSSHキーでアクションを提供しない場合は、リポジトリの設定にアクセスし、提供されたGITHUB_TOKENにRead and Write Permissions許可を提供する必要があります。または、ワークフローファイルに次のように設定して、必要なアクションを許可することもできます。
permissions :
contents : write アクションが機能する前に、ワークフローのwithを構成する必要があります。上記の例にあるwithにこれらを追加できます。 secrets 、ブラケット構文を使用して参照し、GitHubリポジトリのSettings/Secretsメニューに保存する必要があります。 GitHubアクションを使用して、環境変数を設定することの詳細については、こちらをご覧ください。
展開を行うには、次のオプションを構成する必要があります。
| 鍵 | 価値情報 | タイプ | 必須 |
|---|---|---|---|
folder | 展開するリポジトリ内のフォルダー。ビルドスクリプトがbuildという名前のディレクトリにコンパイルされた場合、ここに置くことになります。ルートディレクトリを展開する場合は、配置できます.ここ。また、フォルダパスに~を準備することにより、絶対ファイルパスを使用することもできます。 .gitignoreエントリに一致するファイル/フォルダーは、展開されないことに注意してください。一部のツールは、ビルド出力用の.gitignoreファイルを自動生成します。 | with | はい |
デフォルトでは、アクションはトークン構成を必要とせず、提供されたリポジトリスコープGithubトークンを使用して展開を行います。さらにカスタマイズが必要な場合は、次のオプションを使用して展開タイプを変更できます。
| 鍵 | 価値情報 | タイプ | 必須 |
|---|---|---|---|
token | このオプションは、リポジトリスコープGithubトークンをデフォルトします。ただし、別のリポジトリに展開するなど、さらに多くのアクセス許可が必要な場合は、ここに個人的なアクセストークン（PAT）を追加できます。これはsecrets / withメニューを秘密として保存する必要があります。必要なアクセス許可を持つサービスアカウントを使用することをお勧めします。必要な最小許可スコープを選択することを新しいPATを生成するときに推奨することをお勧めします。暗号化された秘密の作成と使用の詳細については、こちらをご覧ください。 | with | いいえ |
ssh-key | このオプションを秘密として保存されているプライベートSSHキーに設定することにより、SSHを使用して展開するアクションを構成できます。また、既存のSSHクライアント構成を使用するためにtrueに設定することもできます。パブリック/プライベートSSHキーペアを追加する方法の詳細については、このREADMEの展開キーセクションを使用することを参照してください。 | 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のようにフォーマットする必要があります。この構成オプションのtoken入力でPATを使用して、適切に動作する必要があります。 | with | いいえ |
target-folder | 展開フォルダーのコンテンツを展開ブランチの特定のディレクトリにプッシュしたい場合は、ここで指定できます。 | with | いいえ |
commit-message | 統合のためにコミットメッセージをカスタマイズする必要がある場合は、そうすることができます。 | with | いいえ |
clean | このオプションを使用して、展開ソースに存在しなくなった展開先からファイルを削除できます。 1つのユースケースは、プロジェクトがビルドごとに異なるハッシュされたファイルを生成する場合です。 cleanを使用しても.git 、 .github 、または.sshディレクトリには影響しません。このオプションはデフォルトでオンになり、 falseに設定することで切り替えることができます。 | with | いいえ |
clean-exclude | cleanを使用する必要があるが、特定のファイルまたはフォルダーを保存する必要がある場合は、このオプションを使用できます。これには、各パターンをマルチライン文字列に単一の線として含める必要があります。 | with | いいえ |
dry-run | 実際に押し戻さないでください。ただし、代わりにgit push Invocationsで--dry-runを使用します。 | with | いいえ |
single-commit | このオプションは、完全な履歴を維持するのではなく、展開ブランチで単一のコミットを希望する場合は、 trueに切り替えることができます。このオプションを使用すると、既存の履歴が展開ブランチから拭かれます。 | with | いいえ |
force | 以前のバージョンを上書きするためのフォースプッシュの新しい展開。それ以外の場合は、既存の展開に新しい展開を再度回転させようとします。このオプションはデフォルトでオンになり、 falseに設定することで切り替えることができます。これは、単一のブランチに複数の展開がある場合に役立つ場合があります。 | with | いいえ |
attempt-limit | 仕事を一時停止する前に、何回のリベースを試みますか。このオプションはデフォルトで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クライアントを既に設定している場合はssh-keyオプションをtrueに設定して、既存の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これらのファイルを削除する場合は、展開ブランチに直接移動して削除する必要があります。これは、展開スクリプトの偶発的な変更が壊れた変更を作成するのを防ぐためです。
