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 33d89a21e1..a9b98894f2 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 @@ -12,6 +12,7 @@ versions: ghae: '*' ghec: '*' shortTitle: Publish & install with Actions +layout: inline --- {% data reusables.package_registry.packages-ghes-release-stage %} @@ -87,27 +88,36 @@ You can use {% data variables.product.prodname_actions %} to automatically publi {% data reusables.package_registry.actions-configuration %} -The following example demonstrates how you can use {% data variables.product.prodname_actions %} to build {% ifversion not fpt or ghec %}and test{% endif %} your app, and then automatically create a Docker image and publish it to {% data variables.product.prodname_registry %}. +The following example demonstrates how you can use {% data variables.product.prodname_actions %} to build {% ifversion not fpt or ghec %}and test{% endif %} your app, and then automatically create a Docker image and publish it to {% data variables.product.prodname_registry %}. The relevant settings are explained in the code. For full details about each element in a workflow, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)." -Create a new workflow file in your repository (such as `.github/workflows/deploy-image.yml`), and add the following YAML: +Create a new workflow file in your repository (such as `.github/workflows/deploy-image.yml`), and add the following YAML. {% ifversion fpt or ghec %} {% data reusables.package_registry.publish-docker-image %} {% else %} -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} +{% note %} -{% data reusables.actions.actions-use-sha-pinning-comment %} +**Notes:** +- {% data reusables.actions.actions-not-certified-by-github %} +- {% data reusables.actions.actions-use-sha-pinning %} + +{% endnote %} + +```yaml annotate copy +# name: Create and publish a Docker image +# Configures this workflow to run every time a change is pushed to the branch called `release`. on: push: branches: ['release'] jobs: +# This job checks out the repository contents, installs `npm`, uses npm and webpack to build the app, and uploads the built files as an artifact that can be downloaded later in the workflow. +# It assumes that the built files are written to a directory called `public`. run-npm-build: runs-on: ubuntu-latest steps: @@ -121,6 +131,7 @@ jobs: name: webpack artifacts path: public/ +# This job uses `npm test` to test the code. `needs: run-npm-build` makes this job dependent on the `run-npm-build` job. run-npm-test: runs-on: ubuntu-latest needs: run-npm-build @@ -145,21 +156,27 @@ jobs: env: CI: true +# This job publishes the package. `needs: run-npm-test` makes this job dependent on the `run-npm-test` job. build-and-push-image: runs-on: ubuntu-latest needs: run-npm-test {% ifversion ghes or ghae %} + # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job. permissions: contents: read packages: write {% endif %} + # steps: - name: Checkout uses: {% data reusables.actions.action-checkout %} + # Uses the `docker/login-action` action to log in to the registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. - name: Log in to GitHub Docker Registry uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 with: registry: {% ifversion ghae %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %} username: {% raw %}${{ github.actor }}{% endraw %} password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} + # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to {% data variables.product.prodname_registry %}. + # It uses the `tags` parameter to tag the image with the SHA of the commit that triggered the workflow. - name: Build and push Docker image uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 with: @@ -170,318 +187,6 @@ jobs: {% endif %} -The relevant settings are explained in the following table. For full details about each element in a workflow, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)." - - - - - - - - - - - -{% ifversion fpt or ghec %} - - - - - - - - - - - -{% else %} - - - - - - - - - - - - - - - - -{% endif %} - - - - - - -{% ifversion fpt or ghec %} - - - - - - - - - - -{% else %} - - - - -{% endif %} - - - - - - - - - - - - - - - - -{% ifversion fpt or ghec %} - - - - -{% endif %} - - - - - - -{% ifversion fpt or ghec %} - - - - - -{% else %} - - - - -{% endif %} - -
CodeExplanation
-{% raw %} -```yaml -on: - push: - branches: ['release'] -``` -{% endraw %} - - Configures the Create and publish a Docker image workflow to run every time a change is pushed to the branch called release. -
-{% raw %} -```yaml -env: - REGISTRY: ghcr.io - IMAGE_NAME: ${{ github.repository }} -``` -{% endraw %} - - Defines two custom environment variables for the workflow. These are used for the {% data variables.product.prodname_container_registry %} domain, and a name for the Docker image that this workflow builds. -
-{% raw %} -```yaml -jobs: - build-and-push-image: - runs-on: ubuntu-latest -``` -{% endraw %} - - There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu. -
- -```yaml -run-npm-build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: npm install and build webpack - run: | - npm install - npm run build - - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: webpack artifacts - path: public/ -``` - - - This job installs npm and uses it to build the app. -
- -```yaml -run-npm-test: - runs-on: ubuntu-latest - needs: run-npm-build - strategy: - matrix: - os: [ubuntu-latest] - node-version: [12.x, 14.x] - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node-version }}{% endraw %} - - uses: {% data reusables.actions.action-download-artifact %} - with: - name: webpack artifacts - path: public - - name: npm install, and test - run: | - npm install - npm test - env: - CI: true -``` - - - 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. -
-{% 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. -
-{% raw %} -```yaml -permissions: - contents: read - packages: write -``` -{% endraw %} - - Sets the permissions granted to the GITHUB_TOKEN for the actions in this job. -
-{% raw %} -```yaml -- name: Log in to the Container registry - uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 - with: - registry: ${{ env.REGISTRY }} - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} -``` -{% endraw %} - - Creates a step called Log in to the {% data variables.product.prodname_container_registry %}, which logs in to the registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. -
-{% raw %} -```yaml -- name: Extract metadata (tags, labels) for Docker - id: meta - uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 - with: - images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} -``` -{% endraw %} - - This step uses docker/metadata-action to extract tags and labels that will be applied to the specified image. The id "meta" allows the output of this step to be referenced in a subsequent step. The images value provides the base name for the tags and labels. -
-{% raw %} -```yaml -- name: Log in to GitHub Docker Registry - uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 - with: - registry: {% endraw %}{% ifversion ghae %}docker.YOUR-HOSTNAME.com{% else %}docker.pkg.github.com{% endif %}{% raw %} - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} -``` -{% endraw %} - - 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 scoped to the account defined here. -
-{% raw %} -```yaml -- name: Build and push Docker image -``` -{% endraw %} - - Creates a new step called Build and push Docker image. This step runs as part of the build-and-push-image job. -
-{% raw %} -```yaml -uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 -``` -{% endraw %} - - Uses the Docker build-push-action action to build the image, based on your repository's Dockerfile. If the build succeeds, it pushes the image to {% data variables.product.prodname_registry %}. -
-{% raw %} -```yaml -with: -``` -{% endraw %} - - Sends the required parameters to the build-push-action action. These are defined in the subsequent lines. -
-{% raw %} -```yaml -context: . -``` -{% endraw %} - - Defines the build's context as the set of files located in the specified path. For more information, see "Usage." -
-{% raw %} -```yaml -push: true -``` -{% endraw %} - - Pushes this image to the registry if it is built successfully. -
-{% raw %} -```yaml -tags: ${{ steps.meta.outputs.tags }} -labels: ${{ steps.meta.outputs.labels }} -``` -{% endraw %} - - Adds the tags and labels extracted in the "meta" step. -
-{% ifversion ghae %} -{% raw %} -```yaml -tags: | -docker.YOUR-HOSTNAME.com/${{ github.repository }}/octo-image:${{ github.sha }} -``` -{% endraw %} -{% else %} -{% raw %} -```yaml -tags: | -docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }} -``` -{% endraw %} -{% endif %} - - Tags the image with the SHA of the commit that triggered the workflow. -
- This new workflow will run automatically every time you push a change to a branch named `release` in the repository. You can view the progress in the **Actions** tab. A few minutes after the workflow has completed, the new package will visible in your repository. To find your available packages, see "[AUTOTITLE](/packages/learn-github-packages/viewing-packages#viewing-a-repositorys-packages)." @@ -515,37 +220,36 @@ Using the `GITHUB_TOKEN`, instead of a {% data variables.product.pat_v1 %} with 1. Optionally, use {% data variables.package_registry.package-settings-actions-access-role-dropdown %} 1. Open your workflow file. On the line where you log in to the registry, replace your {% data variables.product.pat_generic %} with {% raw %}`${{ secrets.GITHUB_TOKEN }}`{% endraw %}. -For example, this workflow publishes a Docker image to the {% data variables.product.prodname_container_registry %} and uses {% raw %}`${{ secrets.GITHUB_TOKEN }}`{% endraw %} to authenticate. +For example, this workflow publishes a Docker image to the {% data variables.product.prodname_container_registry %} and uses {% raw %}`${{ secrets.GITHUB_TOKEN }}`{% endraw %} to authenticate. For more information, see "[Set up Automated Builds](https://docs.docker.com/docker-hub/builds/)" in the Docker documentation. -```yaml copy +```yaml annotate copy +# name: Demo Push +# This workflow runs when any of the following occur: +# - A push is made to a branch called `main` or `seed` +# - A tag starting with "v" is created +# - A pull request is created or updated on: push: - # Publish `main` as Docker `latest` image. branches: - main - seed - - # Publish `v1.2.3` tags as releases. tags: - v* - - # Run tests for any PRs. pull_request: - + # This creates an environment variable called `IMAGE_NAME ` with the value `ghtoken_product_demo`. env: IMAGE_NAME: ghtoken_product_demo - +# jobs: - # Push image to GitHub Packages. - # See also https://docs.docker.com/docker-hub/builds/ + # This pushes the image to {% data variables.product.prodname_registry %}. push: runs-on: ubuntu-latest permissions: packages: write contents: read - + # steps: - uses: {% data reusables.actions.action-checkout %} @@ -553,20 +257,19 @@ jobs: run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}" - name: Log in to registry - # This is where you will update the {% data variables.product.pat_generic %} to GITHUB_TOKEN run: echo "{% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin - + # - name: Push image run: | IMAGE_ID=ghcr.io/{% raw %}${{ github.repository_owner }}{% endraw %}/$IMAGE_NAME - # Change all uppercase to lowercase + # This changes all uppercase characters to lowercase. IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]') - # Strip git ref prefix from version + # This strips the git ref prefix from the version. VERSION=$(echo "{% raw %}${{ github.ref }}{% endraw %}" | sed -e 's,.*/\(.*\),\1,') - # Strip "v" prefix from tag name + # This strips the "v" prefix from the tag name. [[ "{% raw %}${{ github.ref }}{% endraw %}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//') - # Use Docker `latest` tag convention + # This uses the Docker `latest` tag convention. [ "$VERSION" == "main" ] && VERSION=latest echo IMAGE_ID=$IMAGE_ID echo VERSION=$VERSION diff --git a/data/reusables/actions/actions-not-certified-by-github.md b/data/reusables/actions/actions-not-certified-by-github.md index 6217e98d69..a2e8050089 100644 --- a/data/reusables/actions/actions-not-certified-by-github.md +++ b/data/reusables/actions/actions-not-certified-by-github.md @@ -1 +1 @@ -This workflow uses actions that are not certified by {% data variables.product.prodname_dotcom %}. They are provided by a third-party and are governed by separate terms of service, privacy policy, and support documentation. \ No newline at end of file +This workflow uses actions that are not certified by {% data variables.product.prodname_dotcom %}. They are provided by a third-party and are governed by separate terms of service, privacy policy, and support documentation. diff --git a/data/reusables/package_registry/publish-docker-image.md b/data/reusables/package_registry/publish-docker-image.md index e0de3b4eb4..172d5f83ea 100644 --- a/data/reusables/package_registry/publish-docker-image.md +++ b/data/reusables/package_registry/publish-docker-image.md @@ -1,42 +1,54 @@ -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} +{% note %} -{% data reusables.actions.actions-use-sha-pinning-comment %} +**Notes:** +- {% data reusables.actions.actions-not-certified-by-github %} +- {% data reusables.actions.actions-use-sha-pinning %} + +{% endnote %} + +```yaml annotate copy +# name: Create and publish a Docker image +# Configures this workflow to run every time a change is pushed to the branch called `release`. on: push: branches: ['release'] +# Defines two custom environment variables for the workflow. These are used for the {% data variables.product.prodname_container_registry %} domain, and a name for the Docker image that this workflow builds. env: REGISTRY: {% data reusables.package_registry.container-registry-hostname %} IMAGE_NAME: {% raw %}${{ github.repository }}{% endraw %} +# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu. jobs: build-and-push-image: runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} + # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job. permissions: contents: read packages: write - + # steps: - name: Checkout repository uses: {% data reusables.actions.action-checkout %} - + # Uses the `docker/login-action` action to log in to the {% data variables.product.prodname_container_registry %} registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. - name: Log in to the Container registry uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 with: registry: {% raw %}${{ env.REGISTRY }}{% endraw %} username: {% raw %}${{ github.actor }}{% endraw %} password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - + # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels. - name: Extract metadata (tags, labels) for Docker id: meta uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 with: images: {% raw %}${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}{% endraw %} - + # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to {% data variables.product.prodname_registry %}. + # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository. + # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step. - name: Build and push Docker image uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 with: