|
| 1 | +# Build and Push Docker Image Workflow Documentation |
| 2 | + |
| 3 | +This document provides an overview and detailed explanation of the GitHub Actions workflow that automates the building and pushing of Docker images to the GitHub Container Registry (GHCR). |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The **Build and Push Docker Image** workflow is designed to: |
| 8 | + |
| 9 | +- **Automate Docker Image Builds**: Whenever a new release is published or the workflow is manually triggered, the workflow builds a Docker image from your repository's code. |
| 10 | +- **Push to GitHub Container Registry**: The built Docker image is then pushed to GHCR, tagged appropriately for easy versioning and retrieval. |
| 11 | +- **Support Multiple Platforms**: The workflow is set up to build images for multiple platforms, ensuring broad compatibility. |
| 12 | + |
| 13 | +## Workflow Triggers |
| 14 | + |
| 15 | +The workflow is triggered in two scenarios: |
| 16 | + |
| 17 | +1. **On Release Published**: Automatically runs when a new release is published in the repository. |
| 18 | +2. **Manual Trigger**: Can be manually triggered via the GitHub Actions tab, allowing you to specify a custom release tag. |
| 19 | + |
| 20 | +## Workflow Details |
| 21 | + |
| 22 | +### Name |
| 23 | + |
| 24 | +- **Workflow Name**: `Build and Push Docker Image` |
| 25 | + |
| 26 | +### Trigger Events |
| 27 | + |
| 28 | +```yaml |
| 29 | +on: |
| 30 | + release: |
| 31 | + types: [published] |
| 32 | + workflow_dispatch: |
| 33 | + inputs: |
| 34 | + release_tag: |
| 35 | + description: "Release tag to build and push" |
| 36 | + required: true |
| 37 | +``` |
| 38 | +
|
| 39 | +- **Release Published**: Listens for the `published` event on releases. |
| 40 | +- **Workflow Dispatch**: Allows manual triggering with an input `release_tag`. |
| 41 | + |
| 42 | +### Permissions |
| 43 | + |
| 44 | +```yaml |
| 45 | +permissions: |
| 46 | + contents: read # Allows read access to the repository code |
| 47 | + packages: write # Allows pushing images to GitHub Container Registry |
| 48 | +``` |
| 49 | + |
| 50 | +- **Contents**: Read access to fetch the repository code. |
| 51 | +- **Packages**: Write access to push Docker images to GHCR. |
| 52 | + |
| 53 | +## Job Breakdown |
| 54 | + |
| 55 | +### Job: `build-and-push` |
| 56 | + |
| 57 | +#### Runs On |
| 58 | + |
| 59 | +- **Environment**: `ubuntu-latest` |
| 60 | + |
| 61 | +#### Steps |
| 62 | + |
| 63 | +1. **Checkout Code** |
| 64 | + |
| 65 | + ```yaml |
| 66 | + - name: Checkout code |
| 67 | + uses: actions/checkout@v4 |
| 68 | + ``` |
| 69 | + |
| 70 | + - **Description**: Checks out the repository code so that the workflow can access it. |
| 71 | + |
| 72 | +2. **Set Up Docker Buildx** |
| 73 | + |
| 74 | + ```yaml |
| 75 | + - name: Set up Docker Buildx |
| 76 | + uses: docker/setup-buildx-action@v3 |
| 77 | + ``` |
| 78 | + |
| 79 | + - **Description**: Sets up Docker Buildx for building multi-platform images. |
| 80 | + |
| 81 | +3. **Log in to GitHub Container Registry** |
| 82 | + |
| 83 | + ```yaml |
| 84 | + - name: Log in to GitHub Container Registry |
| 85 | + uses: docker/login-action@v3 |
| 86 | + with: |
| 87 | + registry: ghcr.io |
| 88 | + username: ${{ github.actor }} |
| 89 | + password: ${{ secrets.GITHUB_TOKEN }} |
| 90 | + ``` |
| 91 | + |
| 92 | + - **Description**: Authenticates with GHCR using your GitHub credentials. |
| 93 | + |
| 94 | +4. **Determine the Release Tag** |
| 95 | + |
| 96 | + ```yaml |
| 97 | + - name: Determine the release tag |
| 98 | + id: get_tag |
| 99 | + run: | |
| 100 | + if [ "${{ github.event_name }}" == "release" ]; then |
| 101 | + echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT |
| 102 | + else |
| 103 | + echo "tag=${{ github.event.inputs.release_tag }}" >> $GITHUB_OUTPUT |
| 104 | + fi |
| 105 | + ``` |
| 106 | + |
| 107 | + - **Description**: Determines the Docker image tag: |
| 108 | + - If triggered by a release, uses the release tag. |
| 109 | + - If manually triggered, uses the provided `release_tag` input. |
| 110 | + |
| 111 | +5. **Build and Push Docker Image** |
| 112 | + |
| 113 | + ```yaml |
| 114 | + - name: Build and push Docker image |
| 115 | + uses: docker/build-push-action@v6 |
| 116 | + with: |
| 117 | + context: . |
| 118 | + push: true |
| 119 | + tags: ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}:${{ steps.get_tag.outputs.tag }} |
| 120 | + platforms: linux/arm64,linux/amd64 |
| 121 | + ``` |
| 122 | + |
| 123 | + - **Description**: Builds and pushes the Docker image to GHCR for the specified platforms. |
| 124 | + |
| 125 | +## Platforms |
| 126 | + |
| 127 | +The workflow builds Docker images for the following platforms: |
| 128 | + |
| 129 | +- **linux/arm64** |
| 130 | +- **linux/amd64** |
| 131 | + |
| 132 | +**Note**: Initially, the aim was to build for additional platforms such as `darwin/amd64` and `windows/amd64`, but due to local limitations, the workflow currently builds for the platforms listed above. |
| 133 | + |
| 134 | +## Requirements and Prerequisites |
| 135 | + |
| 136 | +To effectively use this workflow, ensure the following: |
| 137 | + |
| 138 | +- **Dockerfile**: A valid `Dockerfile` must be present at the root of your repository. |
| 139 | +- **GitHub Permissions**: The `GITHUB_TOKEN` provided by GitHub Actions must have the necessary permissions (default settings typically suffice). |
| 140 | +- **Understanding of Docker and GHCR**: Basic knowledge of Docker image building and pushing to GHCR will be beneficial. |
| 141 | + |
| 142 | +## How to Use the Workflow |
| 143 | + |
| 144 | +### Triggering the Workflow on Release |
| 145 | + |
| 146 | +1. **Create a New Release**: |
| 147 | + |
| 148 | + - Navigate to the "Releases" section of your repository. |
| 149 | + - Click on "Draft a new release". |
| 150 | + - Fill in the release details and publish it. |
| 151 | + |
| 152 | +2. **Workflow Execution**: |
| 153 | + |
| 154 | + - Upon publishing, the workflow automatically triggers. |
| 155 | + - It will build the Docker image using the release tag and push it to GHCR. |
| 156 | + |
| 157 | +### Manually Triggering the Workflow |
| 158 | + |
| 159 | +1. **Navigate to GitHub Actions**: |
| 160 | + |
| 161 | + - Go to the "Actions" tab in your repository. |
| 162 | + |
| 163 | +2. **Select the Workflow**: |
| 164 | + |
| 165 | + - Find the **Build and Push Docker Image** workflow from the list. |
| 166 | + |
| 167 | +3. **Run the Workflow**: |
| 168 | + |
| 169 | + - Click on the "Run workflow" button. |
| 170 | + - Provide the required `release_tag` input when prompted. |
| 171 | + - Confirm to start the workflow. |
| 172 | + |
| 173 | +4. **Workflow Execution**: |
| 174 | + |
| 175 | + - The workflow uses the provided `release_tag` to build and push the Docker image. |
| 176 | + |
| 177 | +## Accessing the Pushed Docker Image |
| 178 | + |
| 179 | +The Docker image will be available at: |
| 180 | + |
| 181 | +``` |
| 182 | +ghcr.io/<repository_owner>/<repository_name>:<tag> |
| 183 | +``` |
| 184 | + |
| 185 | +Replace: |
| 186 | + |
| 187 | +- `<repository_owner>`: Your GitHub username or organization name. |
| 188 | +- `<repository_name>`: The name of your repository. |
| 189 | +- `<tag>`: The release tag used during the build. |
| 190 | + |
| 191 | +## Additional Notes |
| 192 | + |
| 193 | +- **Customizing Platforms**: If you need to build for additional platforms, you can modify the `platforms` parameter in the workflow. Be cautious of compatibility and build environment limitations. |
| 194 | +- **Troubleshooting**: |
| 195 | + |
| 196 | + - **Build Failures**: Check the workflow logs for detailed error messages. |
| 197 | + - **Authentication Issues**: Ensure that `GITHUB_TOKEN` has the necessary permissions. |
| 198 | + - **Dockerfile Errors**: Verify that your `Dockerfile` is correctly set up for multi-platform builds. |
| 199 | + |
| 200 | +- **Security Considerations**: |
| 201 | + |
| 202 | + - The `GITHUB_TOKEN` is scoped to the repository and should be kept secure. |
| 203 | + - Avoid echoing sensitive information in the workflow logs. |
| 204 | + |
| 205 | +## Understanding the Workflow's Impact |
| 206 | + |
| 207 | +By integrating this workflow: |
| 208 | + |
| 209 | +- **Consistency**: Ensures that Docker images are consistently built and tagged with each release. |
| 210 | +- **Automation**: Reduces manual efforts in building and pushing Docker images. |
| 211 | +- **Version Control**: Leveraging release tags helps in maintaining versions of your Docker images aligned with your codebase. |
| 212 | + |
| 213 | +## Conclusion |
| 214 | + |
| 215 | +This workflow enhances your CI/CD pipeline by automating the Docker image build and push process. It is essential to familiarize yourself with its steps and requirements to leverage its full potential effectively. Should you have any questions or need further assistance, feel free to reach out or consult the GitHub Actions and Docker documentation. |
| 216 | + |
| 217 | +--- |
| 218 | + |
| 219 | +*This documentation aims to provide a comprehensive understanding of the new workflow and the requirements it places on you. Ensure to review and customize any parts of the workflow to suit your specific needs.* |
0 commit comments