From 948ae9001842821814f60ed2a057ff4cc93ecf31 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:02:55 +0200 Subject: [PATCH 1/3] chore: remove single-use gha-tutorial include Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/includes/gha-tutorial.md | 163 ------------------ .../manuals/build/ci/github-actions/_index.md | 160 +++++++++++++++++ 2 files changed, 160 insertions(+), 163 deletions(-) delete mode 100644 content/includes/gha-tutorial.md diff --git a/content/includes/gha-tutorial.md b/content/includes/gha-tutorial.md deleted file mode 100644 index f4dc92b70c..0000000000 --- a/content/includes/gha-tutorial.md +++ /dev/null @@ -1,163 +0,0 @@ -This tutorial walks you through the process of setting up and using Docker GitHub -Actions for building Docker images, and pushing images to Docker Hub. You will -complete the following steps: - -1. Create a new repository on GitHub. -2. Define the GitHub Actions workflow. -3. Run the workflow. - -To follow this tutorial, you need a Docker ID and a GitHub account. - -### Step one: Create the repository - -Create a GitHub repository and configure the Docker Hub credentials. - -1. Create a new GitHub repository using - [this template repository](https://github.com/dvdksn/clockbox/generate). - - The repository contains a simple Dockerfile, and nothing else. Feel free to - use another repository containing a working Dockerfile if you prefer. - -2. Open the repository **Settings**, and go to **Secrets and variables** > **Actions**. - -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as value. - -4. Create a new - [Personal Access Token (PAT)](/security/for-developers/access-tokens/#create-an-access-token) - for Docker Hub. You can name this token `clockboxci`. - -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name - `DOCKERHUB_TOKEN`. - -With your repository created, and credentials configured, you're now ready for -action! - -### Step two: Set up the workflow - -Set up your GitHub Actions workflow for building and pushing the image to Docker -Hub. - -1. Go to your repository on GitHub and then select the **Actions** tab. -2. Select **set up a workflow yourself**. - - This takes you to a page for creating a new GitHub actions workflow file in - your repository, under `.github/workflows/main.yml` by default. - -3. In the editor window, copy and paste the following YAML configuration. - - ```yaml - name: ci - - on: - push: - branches: - - "main" - - jobs: - build: - runs-on: ubuntu-latest - ``` - - - `name`: the name of this workflow. - - `on.push.branches`: specifies that this workflow should run on every push - event for the branches in the list. - - `jobs`: creates a job ID (`build`) and declares the type of machine that - the job should run on. - -For more information about the YAML syntax used here, see -[Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). - -### Step three: Define the workflow steps - -Now the essentials: what steps to run, and in what order to run them. - - -```yaml -jobs: - build: - runs-on: ubuntu-latest - steps: - - - name: Login to Docker Hub - uses: docker/login-action@v3 - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Build and push - uses: docker/build-push-action@v6 - with: - push: true - tags: ${{ vars.DOCKERHUB_USERNAME }}/clockbox:latest -``` - - -The previous YAML snippet contains a sequence of steps that: - -1. Signs in to Docker Hub, using the - [Docker Login](https://github.com/marketplace/actions/docker-login) action and your Docker Hub credentials. -2. Creates a BuildKit builder instance using the - [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx) action. -3. Builds the container image and pushes it to the Docker Hub repository, using - [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images). - - The `with` key lists a number of input parameters that configures the step: - - - `push`: tells the action to upload the image to a registry after building - it. - - `tags`: tags that specify where to push the image. - -Add these steps to your workflow file. The full workflow configuration should -look as follows: - - -```yaml -name: ci - -on: - push: - branches: - - "main" - -jobs: - build: - runs-on: ubuntu-latest - steps: - - - name: Login to Docker Hub - uses: docker/login-action@v3 - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Build and push - uses: docker/build-push-action@v6 - with: - push: true - tags: ${{ vars.DOCKERHUB_USERNAME }}/clockbox:latest -``` - - -### Run the workflow - -Save the workflow file and run the job. - -1. Select **Commit changes...** and push the changes to the `main` branch. - - After pushing the commit, the workflow starts automatically. - -2. Go to the **Actions** tab. It displays the workflow. - - Selecting the workflow shows you the breakdown of all the steps. - -3. When the workflow is complete, go to your - [repositories on Docker Hub](https://hub.docker.com/repositories). - - If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub! diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md index f9ade474f7..98be726ddd 100644 --- a/content/manuals/build/ci/github-actions/_index.md +++ b/content/manuals/build/ci/github-actions/_index.md @@ -44,6 +44,166 @@ refer to the following sections: ## Get started with GitHub Actions {{< include "gha-tutorial.md" >}} +This tutorial walks you through the process of setting up and using Docker GitHub +Actions for building Docker images, and pushing images to Docker Hub. You will +complete the following steps: + +1. Create a new repository on GitHub. +2. Define the GitHub Actions workflow. +3. Run the workflow. + +To follow this tutorial, you need a Docker ID and a GitHub account. + +### Step one: Create the repository + +Create a GitHub repository and configure the Docker Hub credentials. + +1. Create a new GitHub repository using + [this template repository](https://github.com/dvdksn/clockbox/generate). + + The repository contains a simple Dockerfile, and nothing else. Feel free to + use another repository containing a working Dockerfile if you prefer. + +2. Open the repository **Settings**, and go to **Secrets and variables** > **Actions**. + +3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as value. + +4. Create a new + [Personal Access Token (PAT)](/security/for-developers/access-tokens/#create-an-access-token) + for Docker Hub. You can name this token `clockboxci`. + +5. Add the PAT as a **Repository secret** in your GitHub repository, with the name + `DOCKERHUB_TOKEN`. + +With your repository created, and credentials configured, you're now ready for +action. + +### Step two: Set up the workflow + +Set up your GitHub Actions workflow for building and pushing the image to Docker +Hub. + +1. Go to your repository on GitHub and then select the **Actions** tab. +2. Select **set up a workflow yourself**. + + This takes you to a page for creating a new GitHub actions workflow file in + your repository, under `.github/workflows/main.yml` by default. + +3. In the editor window, copy and paste the following YAML configuration. + + ```yaml + name: ci + + on: + push: + branches: + - "main" + + jobs: + build: + runs-on: ubuntu-latest + ``` + + - `name`: the name of this workflow. + - `on.push.branches`: specifies that this workflow should run on every push + event for the branches in the list. + - `jobs`: creates a job ID (`build`) and declares the type of machine that + the job should run on. + +For more information about the YAML syntax used here, see +[Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). + +### Step three: Define the workflow steps + +Now the essentials: what steps to run, and in what order to run them. + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + - + name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - + name: Build and push + uses: docker/build-push-action@v6 + with: + push: true + tags: ${{ vars.DOCKERHUB_USERNAME }}/clockbox:latest +``` + +The previous YAML snippet contains a sequence of steps that: + +1. Signs in to Docker Hub, using the + [Docker Login](https://github.com/marketplace/actions/docker-login) action and your Docker Hub credentials. +2. Creates a BuildKit builder instance using the + [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx) action. +3. Builds the container image and pushes it to the Docker Hub repository, using + [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images). + + The `with` key lists a number of input parameters that configures the step: + + - `push`: tells the action to upload the image to a registry after building + it. + - `tags`: tags that specify where to push the image. + +Add these steps to your workflow file. The full workflow configuration should +look as follows: + + +```yaml +name: ci + +on: + push: + branches: + - "main" + +jobs: + build: + runs-on: ubuntu-latest + steps: + - + name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - + name: Build and push + uses: docker/build-push-action@v6 + with: + push: true + tags: ${{ vars.DOCKERHUB_USERNAME }}/clockbox:latest +``` + +### Run the workflow + +Save the workflow file and run the job. + +1. Select **Commit changes...** and push the changes to the `main` branch. + + After pushing the commit, the workflow starts automatically. + +2. Go to the **Actions** tab. It displays the workflow. + + Selecting the workflow shows you the breakdown of all the steps. + +3. When the workflow is complete, go to your + [repositories on Docker Hub](https://hub.docker.com/repositories). + + If you see the new repository in that list, it means the GitHub Actions + successfully pushed the image to Docker Hub! ## Next steps From 1c15b54316fe003924ec2873b1799ad835282451 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:04:13 +0200 Subject: [PATCH 2/3] build: align var name with examples Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/ci/github-actions/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md index 98be726ddd..e78d0754e8 100644 --- a/content/manuals/build/ci/github-actions/_index.md +++ b/content/manuals/build/ci/github-actions/_index.md @@ -66,7 +66,7 @@ Create a GitHub repository and configure the Docker Hub credentials. 2. Open the repository **Settings**, and go to **Secrets and variables** > **Actions**. -3. Create a new **Repository variable** named `DOCKER_USERNAME` and your Docker ID as value. +3. Create a new **Repository variable** named `DOCKERHUB_USERNAME` and your Docker ID as value. 4. Create a new [Personal Access Token (PAT)](/security/for-developers/access-tokens/#create-an-access-token) From 63210c974aae0e4a09986b15390bc1d3eb4007c3 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:06:43 +0200 Subject: [PATCH 3/3] chore: fix some linting issues in gha overview Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/ci/github-actions/_index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/manuals/build/ci/github-actions/_index.md b/content/manuals/build/ci/github-actions/_index.md index e78d0754e8..d51d9285f7 100644 --- a/content/manuals/build/ci/github-actions/_index.md +++ b/content/manuals/build/ci/github-actions/_index.md @@ -27,7 +27,7 @@ The following GitHub Actions are available: installs [QEMU](https://github.com/qemu/qemu) static binaries for multi-arch builds. - [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake): - enables using high-level builds with [Bake](../../bake/index.md). + enables using high-level builds with [Bake](../../bake/_index.md). - [Docker Scout](https://github.com/docker/scout-action): analyze Docker images for security vulnerabilities. @@ -69,10 +69,10 @@ Create a GitHub repository and configure the Docker Hub credentials. 3. Create a new **Repository variable** named `DOCKERHUB_USERNAME` and your Docker ID as value. 4. Create a new - [Personal Access Token (PAT)](/security/for-developers/access-tokens/#create-an-access-token) + [personal access token](/security/for-developers/access-tokens/#create-an-access-token) for Docker Hub. You can name this token `clockboxci`. -5. Add the PAT as a **Repository secret** in your GitHub repository, with the name +5. Add the Docker Hub access token as a **Repository secret** in your GitHub repository, with the name `DOCKERHUB_TOKEN`. With your repository created, and credentials configured, you're now ready for @@ -203,7 +203,7 @@ Save the workflow file and run the job. [repositories on Docker Hub](https://hub.docker.com/repositories). If you see the new repository in that list, it means the GitHub Actions - successfully pushed the image to Docker Hub! + successfully pushed the image to Docker Hub. ## Next steps