diff --git a/README.md b/README.md index cecf2928..fc6ebd64 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ [GitHub Actions](https://help.github.com/en/articles/about-github-actions) provides the flexibility to build automated workflows for the software development lifecycle. -GitHub Actions can be used to automate the workflow of creating a new revision of [Azure Container App](https://azure.microsoft.com/en-us/services/container-apps/). -The aca-review-app runs the code contained in the GitHub pull request as an app in the Container App. The review app is then created as a new revision with a Weight of 0, each with a unique URL that can be shared. This is a great way to review and test code changes. +**aca-review-app** can be used to automate the workflow of creating a new revision of [Azure Container App](https://azure.microsoft.com/en-us/services/container-apps/) for review. +This action runs the code contained in the GitHub pull request as an app in the Container App. The review application is then created as a new revision with a Weight of 0, each with a unique URL that can be shared. This is a great way to review and test code changes. This action allows deactivating an app for review that has been created, triggered by the close of a pull request. -Review apps can also be configured to launch automatically with each pull request. Also, when combined with `peter-evans/create-or-update-comment@v2` or similar, you can not only create a revision, but also comment the URL of the created Revision in the Pull Request. +image + +**aca-review-app** can also be configured to launch automatically with each pull request. By integrating with other github actions, it is also possible not only to create revisions, but also to comment the URL of the created revision in a pull request. For more information, please refer to the [eample workflow](./example/). Let's get started today with a [free Azure account](https://azure.com/free/open-source)! @@ -13,6 +15,8 @@ The definition of this GitHub Action is in [action.yml](./action.yml). ## End-to-End Sample Workflows +The **[```example/```](./example/)** in this repository contains a sample project to get started. Please read the hands-on documentation and start building. + ### Dependencies on other GitHub Actions * [Azure Login](https://github.com/Azure/login) Login with your Azure Credentials for Authentication. Once login is done, the next set of Azure Actions in the workflow can re-use the same session within the job. @@ -55,98 +59,65 @@ For using any credentials like Azure Service Principal in your workflow, add the 1. Now in the workflow file in your branch: `.github/workflows/workflow.yml` replace the secret in Azure login action with your secret (Refer to the example below) -### Build and Deploy a Node.JS App to Azure Container App +### Integration to leave comments on Pull Request -```yaml +#### Sample Snipet for the Review Revision Creation -on: [push] -name: Linux_Container_Workflow +You can pass the app URL for review to subsequent actions as follows. -SAMPLE WORKFLOW WILL BE HERE +```yaml +- name: Add revision to ACA + uses: Azure/aca-review-apps@v0.2.0 + id: aca_new_revision + with: + resource-group: + name: + revision-name-suffix: + image: +- name: add new comment to PR + uses: peter-evans/create-or-update-comment@v2 + with: + issue-number: ${{ github.event.pull_request.number }} + body: | + Revision ${{ env.CONTAINERAPP_NAME }}--${{ env.SHORT_HASH }} is created. + ${{ steps.aca_new_revision.outputs.app-url }} ``` -### Example YAML Snippets - -#### Basic sample to create a revision +#### Sample Snipet for the Review Revision Deactivation -```yaml -on: [push, pull_request] -name: Preview Deployment -jobs: - build-and-deploy: - runs-on: ubuntu-latest - env: - RESOURCE_GROUP: - CONTAINER_APP_NAME: - DOCKER_IMAGE_NAME: - # REVISION_NAME_SUFFIX: # Optional: Default is github commit hash - steps: - - name: 'Checkout GitHub Action' - uses: actions/checkout@master - - name: 'Login via Azure CLI' - uses: azure/login@v1 - with: - creds: ${{ secrets.AZURE_CREDENTIALS }} - - name: 'Create a new Container App revision' - uses: azure/aca-preview@v0.1 - with: - resource-group: ${{ env.RESOURCE_GROUP }} - name: ${{ env.CONTAINER_APP_NAME }} - image: ${{ env.DOCKER_IMAGE_NAME }} -``` - -##### Using customize suffice instead of git commit hash +This action can also automatically deactivate revisions. +However, this flow must be triggered only when the pull request is closed. For more information, see the [sample](./example/) implementation. ```yaml -- name: 'Create a new Container App revision' - uses: azure/aca-preview@v0.1 +- name: Deactivate Preview revision on ACA + uses: Azure/aca-review-apps@v0.2.0 with: - resource-group: ${{ env.RESOURCE_GROUP }} - name: ${{ env.CONTAINER_APP_NAME }} - image: ${{ env.DOCKER_IMAGE_NAME }} - revision-name-suffix: ${{ env.REVISION_NAME_SUFFIX }} + resource-group: + name: + revision-name-suffix: + image: + deactivate-revision-mode: true #IMPORTANT!! + +- name: Find Comment + uses: peter-evans/find-comment@v2 + id: fc with: -``` + issue-number: ${{ github.event.pull_request.number }} + comment-author: "github-actions[bot]" + body-includes: Revision ${{ env.CONTAINERAPP_NAME }}--${{ env.SHORT_HASH }} is created. -#### Create and Deactivate an action - -```yaml -on: [push, pull_request] -name: Preview Deployment -jobs: - build-and-deploy: - runs-on: ubuntu-latest - env: - RESOURCE_GROUP: - CONTAINER_APP_NAME: - DOCKER_IMAGE_NAME: - steps: - - name: 'Checkout GitHub Action' - uses: actions/checkout@master - - name: 'Login via Azure CLI' - uses: azure/login@v1 - with: - creds: ${{ secrets.AZURE_CREDENTIALS }} - # Revision Creation - - name: 'Create a new Container App revision' - uses: azure/aca-preview@v0.1 - with: - resource-group: ${{ env.RESOURCE_GROUP }} - name: ${{ env.CONTAINER_APP_NAME }} - image: ${{ env.DOCKER_IMAGE_NAME }} - # Revision Deactivation - - name: Deactivate Preview Deployment - if: github.event.action == 'closed' - uses: azure/aca-preview@v0.0.1 - with: - deactivate-revision-mode: ture - resource-group: ${{ env.RESOURCE_GROUP }} - name: ${{ env.CONTAINER_APP_NAME }} - image: ${{ env.DOCKER_IMAGE_NAME }} +- name: add new comment to PR + if: steps.fc.outputs.comment-id != '' + uses: peter-evans/create-or-update-comment@v2 + with: + comment-id: ${{ steps.fc.outputs.comment-id }} + edit-mode: replace + body: | + Revision ${{ env.CONTAINERAPP_NAME }}--${{ env.SHORT_HASH }} is deactivated. ``` -### How to develop/test this Action +### How to Develop/Test this Action #### Debug with breakpoints on Visual Studio Code diff --git a/action.yml b/action.yml index 9ed11939..1af33ddd 100644 --- a/action.yml +++ b/action.yml @@ -20,8 +20,8 @@ outputs: app-url: description: 'Deployed App URL' branding: - icon: 'azure-logo.svg' + icon: 'check-circle' color: 'blue' runs: using: 'node16' - main: 'lib/main.js' \ No newline at end of file + main: 'lib/main.js' diff --git a/example/.github/workflows/build-deploy-deactivate-revision.yml b/example/.github/workflows/build-deploy-deactivate-revision.yml new file mode 100644 index 00000000..b54b3855 --- /dev/null +++ b/example/.github/workflows/build-deploy-deactivate-revision.yml @@ -0,0 +1,121 @@ +name: Build, Deploy and Deactivate ACA revision + +on: + pull_request: + types: [opened, synchronize, closed] + +permissions: + # for `create-or-update-comment` action + pull-requests: write + issues: write + + # for Azure login with OIDC + # id-token: write + +env: + CONTAINER_REGISTRY: acracapreview.azurecr.io # TODO: container registry name like `foobar.azurecr.io` + RESOURCE_GROUP_NAME: aca-preview-hands-on-rg # TODO: resource group name where the target Azure Container Apps resource in + CONTAINERAPP_NAME: aca-preview-app # TODO: Azure Container Apps resource name + +jobs: + add-revision: + runs-on: ubuntu-18.04 + if: github.event.action != 'closed' + + steps: + - name: Checkout to the branch + uses: actions/checkout@v2 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v1 + + - name: Set repository name to env + run: | + echo "REPOSITORY_NAME=${GITHUB_REPOSITORY#${GITHUB_REPOSITORY_OWNER}/}" >> $GITHUB_ENV + echo "SHORT_HASH=${COMMIT_HASH:0:7}" >> $GITHUB_ENV + env: + COMMIT_HASH: ${{ github.event.pull_request.head.sha }} + + - name: Log in to container registry + uses: docker/login-action@v1 + with: + registry: ${{ env.CONTAINER_REGISTRY }} + username: ${{ secrets.CONTAINER_REGISTRY_USERNAME }} + password: ${{ secrets.CONTAINER_REGISTRY_PASSWORD }} + + - name: Build and push container image to registry + uses: docker/build-push-action@v2 + with: + push: true + tags: ${{ env.CONTAINER_REGISTRY }}/${{ env.REPOSITORY_NAME }}:${{ github.event.pull_request.head.sha }} + file: ./Dockerfile + context: ./ + + - name: Azure Login + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + - name: Add revision to ACA + uses: Azure/aca-review-apps@v0.2.0 + id: aca_new_revision + with: + resource-group: ${{ env.RESOURCE_GROUP_NAME }} + name: ${{ env.CONTAINERAPP_NAME }} + revision-name-suffix: ${{ env.SHORT_HASH }} + image: ${{ env.CONTAINER_REGISTRY }}/${{ env.REPOSITORY_NAME }}:${{ github.event.pull_request.head.sha }} + + - name: add new comment to PR + uses: peter-evans/create-or-update-comment@v2 + with: + issue-number: ${{ github.event.pull_request.number }} + body: | + Revision ${{ env.CONTAINERAPP_NAME }}--${{ env.SHORT_HASH }} is created. + ${{ steps.aca_new_revision.outputs.app-url }} + + deactivate-revision: + runs-on: ubuntu-18.04 + if: github.event.action != 'opened' + + steps: + - name: Set short version of Commit hash to env + run: | + echo "REPOSITORY_NAME=${GITHUB_REPOSITORY#${GITHUB_REPOSITORY_OWNER}/}" >> $GITHUB_ENV + echo "SHORT_HASH=${COMMIT_HASH:0:7}" >> $GITHUB_ENV + env: + COMMIT_HASH: | + ${{ + github.event.action == 'closed' && github.event.pull_request.head.sha || + github.event.action == 'synchronize' && github.event.before + }} + + - name: Azure Login + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + - name: Deactivate Preview revision on ACA + uses: Azure/aca-review-apps@v0.2.0 + with: + resource-group: ${{ env.RESOURCE_GROUP_NAME }} + name: ${{ env.CONTAINERAPP_NAME }} + revision-name-suffix: ${{ env.SHORT_HASH }} + deactivate-revision-mode: true + image: "THIS_VALUE_IS_IGNORED_IN_DEACTIVATION_MODE" + + - name: Find Comment + uses: peter-evans/find-comment@v2 + id: fc + with: + issue-number: ${{ github.event.pull_request.number }} + comment-author: "github-actions[bot]" + body-includes: Revision ${{ env.CONTAINERAPP_NAME }}--${{ env.SHORT_HASH }} is created. + + - name: add new comment to PR + if: steps.fc.outputs.comment-id != '' + uses: peter-evans/create-or-update-comment@v2 + with: + comment-id: ${{ steps.fc.outputs.comment-id }} + edit-mode: replace + body: | + Revision ${{ env.CONTAINERAPP_NAME }}--${{ env.SHORT_HASH }} is deactivated. diff --git a/example/Dockerfile b/example/Dockerfile new file mode 100644 index 00000000..9e777d6a --- /dev/null +++ b/example/Dockerfile @@ -0,0 +1 @@ +FROM mcr.microsoft.com/azuredocs/containerapps-helloworld:latest \ No newline at end of file diff --git a/example/README.md b/example/README.md new file mode 100644 index 00000000..d252c411 --- /dev/null +++ b/example/README.md @@ -0,0 +1,140 @@ +# \[Azure/aca-review-apps\] Tryout! + +## Preparation + +### Build Environment + +Fork or clone this repository and create your own repository as follows: + +```bash +cp -rf sample-project +git init +git add . +git commit -m "first commit" +git branch -M main +git remote add origin +git push -u origin main +``` + +### Login to Azure CLI + +```bash +az login +``` + +### Set Environment Variables + +```bash +SUBSCRIPTION_ID="your-subscription-id" +RESOURCE_GROUP="your-resource-group-name" +LOCATION="your-rg-location" +CONTAINERAPPS_ENVIRONMENT="your-container-app-environment-name" +CONTAINER_APP_NAME="your-container-app-namae" +CONTAINER_REGISTRY="your-container-registry-name" +REPOSITORY_NAME="your-repository-name" +SERVICE_PRINCIPAL_NAME="your-service-principal-name" +``` + +### Create a resource group + +```bash +az group create \ + --name $RESOURCE_GROUP \ + --location $LOCATION +``` + +### Create a container registry + +```bash +az acr create --resource-group $RESOURCE_GROUP --name $CONTAINER_REGISTRY --sku Basic --admin-enabled true +``` + +### Log in to registry + +```bash +az acr login --name $CONTAINER_REGISTRY +``` + +### Build image and tag it + +```bash +docker build -t $REPOSITORY_NAME . +docker tag $REPOSITORY_NAME $CONTAINER_REGISTRY.azurecr.io/$REPOSITORY_NAME:v1 +``` + +### Push image to registry + +```bash +docker push $CONTAINER_REGISTRY.azurecr.io/$REPOSITORY_NAME:v1 +``` + +### Create an environment + +```bash +az containerapp env create \ + --name $CONTAINERAPPS_ENVIRONMENT \ + --resource-group $RESOURCE_GROUP \ + --location $LOCATION +``` + +### Create a container app + +```bash +az containerapp create \ + --image $CONTAINER_REGISTRY.azurecr.io/$REPOSITORY_NAME:v1 \ + --name $CONTAINER_APP_NAME \ + --resource-group $RESOURCE_GROUP \ + --environment $CONTAINERAPPS_ENVIRONMENT \ + --ingress external \ + --target-port 80 +``` + +## Preview Deployment Automation using `aca-review-apps` action + +### Create a service principa + +```bash +az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \ + --role contributor \ + --scopes /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP +``` + +### Create GitHub secrets + +| Secret Name | Value| +| ---- | ---- | +| AZURE_CREDENTIALS | your service principal | +| CONTAINER_REGISTRY_PASSWORD | your container registry user name | +| CONTAINER_REGISTRY_USERNAME | your container registry password | + +### Create workflow file + +Modify following environment variables in the [sample workflow](.github/workflows/build-deploy-deactivate-revision.yml) to your own values + +- CONTAINER_REGISTRY +- RESOURCE_GROUP_NAME +- CONTAINERAPP_NAME + +### Push code to main branch + +```bash +git add . +git commit -m "update workflow file" +git push origin main +``` + +## Validate workflow + +1. Create a new branch, commit and push +2. Open a Pull Request to main branch + 1. Confirm that the workflow has successfully run and that the revision URL for the preview is pasted in the comments of Pulll request. + 2. Also confirm in Azure Portal that a revision with a traffic weight of 0 has been issued. +3. Close Pull request + 1. Confirm that the workflow has successfully run and that the pull request comments have been updated + 2. Confirm that the revision you created is deactivated on Azure Portal as well. + +## Clean up resources + +```bash +az group delete --name $RESOURCE_GROUP +``` diff --git a/example/README_JP.md b/example/README_JP.md new file mode 100644 index 00000000..dc36a4f9 --- /dev/null +++ b/example/README_JP.md @@ -0,0 +1,139 @@ +# \[Azure/aca-review-apps\] ハンズオン手順書 + +## 準備 + +### 環境構築 +このレポジトリをフォークするか，クローンして以下の手順で自分のレポジトリを作成 + +```bash +cp -rf sample-project <適切な場所> +git init +git add . +git commit -m "first commit" +git branch -M main +git remote add origin <自分のレポジトリURL> +git push -u origin main +``` + +### ログイン + +```bash +az login +``` + +### 環境変数設定 + +```bash +SUBSCRIPTION_ID="サブスクリプションID" +RESOURCE_GROUP="リソースグループ名" +LOCATION="リソースロケーション" +CONTAINERAPPS_ENVIRONMENT="Container Apps環境名" +CONTAINER_APP_NAME="コンテナーアプリ名" +CONTAINER_REGISTRY="コンテナレジストリ名" +REPOSITORY_NAME="レポジトリ名" +SERVICE_PRINCIPAL_NAME="サービスプリンシパル名" +``` + +### リソースグループ作成 + +```bash +az group create \ + --name $RESOURCE_GROUP \ + --location $LOCATION +``` + +### ACRインスタンス作成 + +```bash +az acr create --resource-group $RESOURCE_GROUP --name $CONTAINER_REGISTRY --sku Basic --admin-enabled true +``` + +### ACRログイン + +```bash +az acr login --name $CONTAINER_REGISTRY +``` + +### イメージをビル＆タグつける + +```bash +docker build -t $REPOSITORY_NAME . +docker tag $REPOSITORY_NAME $CONTAINER_REGISTRY.azurecr.io/$REPOSITORY_NAME:v1 +``` + +### DockerイメージをACRにpush + +```bash +docker push $CONTAINER_REGISTRY.azurecr.io/$REPOSITORY_NAME:v1 +``` + +### コンテナーアプリ環境作成 + +```bash +az containerapp env create \ + --name $CONTAINERAPPS_ENVIRONMENT \ + --resource-group $RESOURCE_GROUP \ + --location $LOCATION +``` + +### コンテナーアプリ作成 + +```bash +az containerapp create \ + --image $CONTAINER_REGISTRY.azurecr.io/$REPOSITORY_NAME:v1 \ + --name $CONTAINER_APP_NAME \ + --resource-group $RESOURCE_GROUP \ + --environment $CONTAINERAPPS_ENVIRONMENT \ + --ingress external \ + --target-port 80 +``` + +## aca-review-appsを仕様したプレビューデプロイ自動化 + +### サービスプリンシパルを発行 + +```bash +az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \ + --role contributor \ + --scopes /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP +``` + +### GitHubシークレットを作成 + +| シークレット名 | 値 | +| ---- | ---- | +| AZURE_CREDENTIALS | サービスプリンシパル | +| CONTAINER_REGISTRY_PASSWORD | ACRユーザ名 | +| CONTAINER_REGISTRY_USERNAME | ACRパスワード | + +### ワークフローを定義 + +[サンプルワークフロー](./.github/workflows/build-deploy-deactivate-revision.yml)内の環境変数を自分用に修正 + +- CONTAINER_REGISTRY +- RESOURCE_GROUP_NAME +- CONTAINERAPP_NAME + +### mainブランチへpush + +```bash +git add . +git commit -m "hoge" +git push origin main +``` + +## 実際に体験 + +1. 適当なブランチを切って，適当なコミット（e.g. コメントアウト）をしてpush +2. mainに対してPRを立てる + 1. アクションが正常に動作し，PRのコメントにプレビューURLが貼られることを確認 + 2. Azure Potal上でトラフィック0のリビジョンが発行されていることを確認 +3. PRをマージしcloseする + 1. アクションが正常に動作し，PRのコメントが更新されていることを確認 + 2. Azure Portal上で作成したリビジョンがデアクティブになっていることを確認 + +## リソースのクリーンアップ + +```bash +az group delete --name $RESOURCE_GROUP +```