From 21f917bd5af88cd777f0a18711c28d43fc533eb5 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Tue, 18 May 2021 19:00:52 -0400 Subject: [PATCH] Update Docker Registry workflow examples for docker/build-push-action@v2 (#6317) --- .../guides/publishing-docker-images.md | 78 +++++++---- ...nstalling-a-package-with-github-actions.md | 132 ++++++++---------- .../github-actions/docker-tag-with-ref.md | 2 +- 3 files changed, 110 insertions(+), 102 deletions(-) diff --git a/content/actions/guides/publishing-docker-images.md b/content/actions/guides/publishing-docker-images.md index 94b83f0865..b8974369f9 100644 --- a/content/actions/guides/publishing-docker-images.md +++ b/content/actions/guides/publishing-docker-images.md @@ -51,14 +51,17 @@ In this guide, we will use the Docker `build-push-action` action to build the Do {% data reusables.github-actions.release-trigger-workflow %} -In the example workflow below, we use the Docker `build-push-action` action to build the Docker image and, if the build succeeds, push the built image to Docker Hub. +In the example workflow below, we use the Docker `login-action` and `build-push-action` actions to build the Docker image and, if the build succeeds, push the built image to Docker Hub. To push to Docker Hub, you will need to have a Docker Hub account, and have a Docker Hub repository created. For more information, see "[Pushing a Docker container image to Docker Hub](https://docs.docker.com/docker-hub/repos/#pushing-a-docker-container-image-to-docker-hub)" in the Docker documentation. -The `build-push-action` options required for Docker Hub are: +The `login-action` options required for Docker Hub are: * `username` and `password`: This is your Docker Hub username and password. We recommend storing your Docker Hub username and password as secrets so they aren't exposed in your workflow file. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." -* `repository`: Your Docker Hub repository in the format `DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY`. + +The `build-push-action` options required for Docker Hub are: +* `tags`: The tag of your new image in the format `DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY:VERSION`. You can set a single tag as shown below, or specify multiple tags in a list. +* `push`: If set to `true`, the image will be pushed to the registry if it is built successfully. {% raw %} ```yaml{:copy} @@ -73,13 +76,16 @@ jobs: steps: - name: Check out the repo uses: actions/checkout@v2 - - name: Push to Docker Hub - uses: docker/build-push-action@v1 + - name: Log in to Docker Hub + uses: docker/login-action@v1 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - repository: my-docker-hub-namespace/my-docker-hub-repository - tag_with_ref: true + - name: Push to Docker Hub + uses: docker/build-push-action@v2 + with: + push: true + tags: my-docker-hub-namespace/my-docker-hub-repository:latest ``` {% endraw %} @@ -89,14 +95,16 @@ jobs: {% data reusables.github-actions.release-trigger-workflow %} -In the example workflow below, we use the Docker `build-push-action` action to build the Docker image, and if the build succeeds, push the built image to {% data variables.product.prodname_registry %}. - -The `build-push-action` options required for {% data variables.product.prodname_registry %} are: +In the example workflow below, we use the Docker `login-action` and `build-push-action` actions to build the Docker image, and if the build succeeds, push the built image to {% data variables.product.prodname_registry %}. +The `login-action` options required for {% data variables.product.prodname_registry %} are: +* `registry`: Must be set to `docker.pkg.github.com`. * `username`: You can use the {% raw %}`${{ github.actor }}`{% endraw %} context to automatically use the username of the user that triggered the workflow run. For more information, see "[Context and expression syntax for GitHub Actions](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)." * `password`: You can use the automatically-generated `GITHUB_TOKEN` secret for the password. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token)." -* `registry`: Must be set to `docker.pkg.github.com`. -* `repository`: Must be set in the format `OWNER/REPOSITORY/IMAGE_NAME`. For example, for an image named `octo-image` stored on {% data variables.product.prodname_dotcom %} at `http://github.com/octo-org/octo-repo`, the `repository` option should be set to `octo-org/octo-repo/octo-image`. + +The `build-push-action` options required for {% data variables.product.prodname_registry %} are: +* `tags`: Must be set in the format `docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION`. For example, for an image named `octo-image` stored on {% data variables.product.prodname_dotcom %} at `http://github.com/octo-org/octo-repo`, the `tags` option should be set to `docker.pkg.github.com/octo-org/octo-repo/octo-image:latest`. You can set a single tag as shown below, or specify multiple tags in a list. +* `push`: If set to `true`, the image will be pushed to the registry if it is built successfully. ```yaml{:copy} name: Publish Docker image @@ -113,24 +121,28 @@ jobs: steps: - name: Check out the repo uses: actions/checkout@v2 - - name: Push to GitHub Packages - uses: docker/build-push-action@v1 + - name: Log in to GitHub Docker Registry + uses: docker/login-action@v1 with: + registry: {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %} username: {% raw %}${{ github.actor }}{% endraw %} password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - registry: docker.pkg.github.com - repository: my-org/my-repo/my-image - tag_with_ref: true - + - name: Build container image + uses: docker/build-push-action@v2 + with: + push: true + tags: | + {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}{% raw %}/${{ github.repository }}/octo-image:${{ github.sha }}{% endraw %} + {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}{% raw %}/${{ github.repository }}/octo-image:${{ github.ref }}{% endraw %} ``` {% data reusables.github-actions.docker-tag-with-ref %} ### Publishing images to Docker Hub and {% data variables.product.prodname_registry %} -In a single workflow, you can publish your Docker image to multiple registries by using the `build-push-action` action for each registry. +In a single workflow, you can publish your Docker image to multiple registries by using the `login-action` and `build-push-action` actions for each registry. -The following example workflow uses the `build-push-action` steps from the previous sections ("[Publishing images to Docker Hub](#publishing-images-to-docker-hub)" and "[Publishing images to {% data variables.product.prodname_registry %}](#publishing-images-to-github-packages)") to create a single workflow that pushes to both registries. +The following example workflow uses the steps from the previous sections ("[Publishing images to Docker Hub](#publishing-images-to-docker-hub)" and "[Publishing images to {% data variables.product.prodname_registry %}](#publishing-images-to-github-packages)") to create a single workflow that pushes to both registries. ```yaml{:copy} name: Publish Docker image @@ -147,21 +159,27 @@ jobs: steps: - name: Check out the repo uses: actions/checkout@v2 - - name: Push to Docker Hub - uses: docker/build-push-action@v1 + - name: Log in to Docker Hub + uses: docker/login-action@v1 with: username: {% raw %}${{ secrets.DOCKER_USERNAME }}{% endraw %} password: {% raw %}${{ secrets.DOCKER_PASSWORD }}{% endraw %} - repository: my-docker-hub-namespace/my-docker-hub-repository - tag_with_ref: true - - name: Push to GitHub Packages - uses: docker/build-push-action@v1 + - name: Log in to GitHub Docker Registry + uses: docker/login-action@v1 with: + registry: {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %} username: {% raw %}${{ github.actor }}{% endraw %} password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - registry: docker.pkg.github.com - repository: my-org/my-repo/my-image - tag_with_ref: true + - name: Push to Docker Hub + uses: docker/build-push-action@v2 + with: + push: true + tags: my-docker-hub-namespace/my-docker-hub-repository:{% raw %}${{ github.ref }}{% endraw %} + - name: Build container image + uses: docker/build-push-action@v2 + with: + push: true + tags: {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}{% raw %}/${{ github.repository }}/my-image:${{ github.ref }}{% endraw %} ``` -The above workflow checks out the {% data variables.product.prodname_dotcom %} repository, and uses the `build-push-action` action twice to build and push the Docker image to Docker Hub and {% data variables.product.prodname_registry %}. For both steps, it sets the `build-push-action` option [`tag_with_ref`](https://github.com/marketplace/actions/build-and-push-docker-images#tag_with_ref) to automatically tag the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a {% data variables.product.prodname_dotcom %} release, so the reference for both registries will be the Git tag for the release. +The above workflow checks out the {% data variables.product.prodname_dotcom %} repository, uses the `login-action` twice to log in to both registries, and then uses the `build-push-action` action twice to build and push the Docker image to Docker Hub and {% data variables.product.prodname_registry %}. For both steps, it tags the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a {% data variables.product.prodname_dotcom %} release, so the reference for both registries will be the Git tag for the release. diff --git a/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md b/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md index a370519036..706e6ea3a9 100644 --- a/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md +++ b/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md @@ -132,23 +132,27 @@ The following example demonstrates how you can use {% data variables.product.pro CI: true build-and-push-image: - runs-on: ubuntu-latest {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %} + runs-on: ubuntu-latest + needs: run-npm-test {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %} permissions: contents: read packages: write {% endif %} - needs: run-npm-test steps: - name: Checkout uses: actions/checkout@v2 + - name: Log in to GitHub Docker Registry + uses: docker/login-action@v1 + with: + registry: {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %} + username: {% raw %}${{ github.actor }}{% endraw %} + password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - name: Build container image - uses: docker/build-push-action@v1 - with: {% raw %} - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - registry: {% endraw %}{% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}{% raw %} - repository: ${{ github.repository }}/octo-image {% endraw %} - tag_with_sha: true - tag_with_ref: true + uses: docker/build-push-action@v2 + with: + push: true + tags: | + {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.sha }}{% endraw %} + {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.ref }}{% endraw %} ``` The relevant settings are explained in the following table: @@ -227,7 +231,25 @@ on: This job uses npm test to test the code. The needs: run-npm-build command makes this job dependent on the run-npm-build job. - {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %} + + + + + +{% raw %} +```yaml + build-and-push-image: + runs-on: ubuntu-latest + needs: run-npm-test +``` +{% endraw %} + + + This job publishes the package. The needs: run-npm-test command makes this job dependent on the run-npm-test job. + + + + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.1" or currentVersion == "github-ae@next" %} @@ -248,12 +270,17 @@ on: {% raw %} ```yaml - - name: Build container image + - name: Log in to GitHub Docker Registry + uses: docker/login-action@v1 + with: + registry: {% endraw %}{% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}{% raw %} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} ``` {% endraw %} - Creates a new step called Build container image. This step runs as part of the build-and-push-image job. The needs: run-npm-test command makes this job dependent on the run-npm-test job. + Creates a new step called Log in to GitHub Docker Registry, which logs in to the registry using the account and password that will publish the packages. Once published, the packages are owned by the account defined here. @@ -261,7 +288,20 @@ on: {% raw %} ```yaml -uses: docker/build-push-action@v1 + - name: Build container image + ``` +{% endraw %} + + + Creates a new step called Build container image. This step runs as part of the build-and-push-image job. + + + + + +{% raw %} + ```yaml +uses: docker/build-push-action@v2 ``` {% endraw %} @@ -287,75 +327,25 @@ with: {% raw %} ```yaml -username: ${{ github.actor }} +push: true ``` {% endraw %} - Defines the user account that will publish the packages. Once published, the packages are owned by the account defined here. - - - - - -{% raw %} - ```yaml -password: ${{ secrets.GITHUB_TOKEN }} - ``` -{% endraw %} - - - Defines the password that is used to access {% data variables.product.prodname_registry %}. + Push this image to the registry if it is built successfully. ```yaml -registry: {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %} +tags: | + {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.sha }}{% endraw %} + {% if currentVersion == "github-ae@latest" %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}/{% raw %}${{ github.repository }}/octo-image:${{ github.ref }}{% endraw %} ``` - Defines the registry that will host the resulting packages. This example uses {% data variables.product.prodname_registry %}.{% if currentVersion == "github-ae@latest" %} Replace YOUR-HOSTNAME with the name of your enterprise.{% endif %} {% if currentVersion == "free-pro-team@latest" %} If you're using the {% data variables.product.prodname_container_registry %}, then use ghcr.io as the hostname.{% endif %} - - - - - -{% raw %} - ```yaml -repository: ${{ github.repository }}/octo-image - ``` -{% endraw %} - - - Defines which repository will host the resulting package, and sets the name of the published package. Replace octo-image with the name you want for your package. - - - - - -{% raw %} - ```yaml -tag_with_sha: true - ``` -{% endraw %} - - - Tags the published package with the first seven characters of the commit's SHA. For example, sha-2f2d842. - - - - - -{% raw %} - ```yaml -tag_with_ref: true - ``` -{% endraw %} - - - Tags the published package with the git ref. This can be the name of the branch used to create the package. + Tags the published package with the git ref (for example, the name of the branch used to create the package) as well as the commit SHA. @@ -452,4 +442,4 @@ jobs: docker push $IMAGE_ID:$VERSION{% endraw %} ``` -{% endif %} \ No newline at end of file +{% endif %} diff --git a/data/reusables/github-actions/docker-tag-with-ref.md b/data/reusables/github-actions/docker-tag-with-ref.md index ec4687f6e1..ac946a65dc 100644 --- a/data/reusables/github-actions/docker-tag-with-ref.md +++ b/data/reusables/github-actions/docker-tag-with-ref.md @@ -1 +1 @@ -The above workflow checks out the {% data variables.product.prodname_dotcom %} repository, and uses the `build-push-action` action to build and push the Docker image. It sets the `build-push-action` option [`tag_with_ref`](https://github.com/marketplace/actions/build-and-push-docker-images#tag_with_ref) to automatically tag the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a {% data variables.product.prodname_dotcom %} release, so the reference will be the Git tag for the release. +The above workflow checks out the {% data variables.product.prodname_dotcom %} repository, uses the `login-action` to log in to the registry, and then uses the `build-push-action` action to build and push the Docker image. It tags the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a {% data variables.product.prodname_dotcom %} release, so the reference will be the Git tag for the release.