{"id":14063545,"url":"https://github.com/3shape/docker-ci","last_synced_at":"2025-07-29T15:33:59.181Z","repository":{"id":45164110,"uuid":"212782585","full_name":"3shape/docker-ci","owner":"3shape","description":"Helps you build rock-solid Docker images. Written as a Powershell Core module. Install from PSGallery.","archived":true,"fork":false,"pushed_at":"2022-01-04T12:13:51.000Z","size":209,"stargazers_count":5,"open_issues_count":11,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-13T07:05:12.885Z","etag":null,"topics":["cmdlets","docker","docker-images","hacktoberfest","hacktoberfest2020","integration-testing","linting","module","powershell","powershellcore","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/3shape.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2019-10-04T09:45:25.000Z","updated_at":"2024-07-19T07:10:15.000Z","dependencies_parsed_at":"2022-09-25T20:11:23.233Z","dependency_job_id":null,"html_url":"https://github.com/3shape/docker-ci","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3shape%2Fdocker-ci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3shape%2Fdocker-ci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3shape%2Fdocker-ci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3shape%2Fdocker-ci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/3shape","download_url":"https://codeload.github.com/3shape/docker-ci/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228028479,"owners_count":17858340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmdlets","docker","docker-images","hacktoberfest","hacktoberfest2020","integration-testing","linting","module","powershell","powershellcore","unit-testing"],"created_at":"2024-08-13T07:03:23.492Z","updated_at":"2024-12-04T01:30:58.693Z","avatar_url":"https://github.com/3shape.png","language":"PowerShell","readme":"[![Build Status](https://dev.azure.com/3ShapeOld/Docker-CI/_apis/build/status/3shape.docker-ci?branchName=master)](https://dev.azure.com/3ShapeOld/Docker-CI/_build/latest?definitionId=10\u0026branchName=master)\n[![codecov](https://codecov.io/gh/3shape/docker-ci/branch/master/graph/badge.svg)](https://codecov.io/gh/3shape/docker-ci)\n[![PS Gallery](https://img.shields.io/badge/install-PS%20Gallery-blue.svg)](https://www.powershellgallery.com/packages/Docker-CI/)\n\n# docker-ci\n\nPowerShell Core module to build and test Docker images.\nThe module comes with CmdLets to perform the most commonly used tasks with regards to building docker images:\n\n- Build\n- Tests\n- Lint\n- Login\n- Pull\n- Push\n- Tag\n- Inspect (not implemented yet)\n\nFor each tasks there is a corresponding CmdLet:\n\n- Invoke-DockerBuild\n- Invoke-DockerTests\n- Invoke-DockerLint\n- Invoke-DockerLogin\n- Invoke-DockerPull\n- Invoke-DockerPush\n- Invoke-DockerTag\n\nTo run, just do\n\n```powershell\nPS C:\\docker\u003e Invoke-DockerBuild .\n```\nand so on.\n\n## Prerequisite\n\n* PowerShell core \u003e= 6.0 is needed.\n* Docker Engine \u003e= 20.10.0 or Docker Desktop \u003e= 3.0.0 is needed\n\n## Installation\n\n```powershell\nPS C:\\docker\u003e Install-Module Docker-ci -Repository PSGallery\n```\n\n## Examples\nIn the following section we'll cover how to use the module to add testing and linting to an existing Dockerfile. I am assuming you repository looks like this at the moment:\n\n```powershell\nPS C:\\docker\u003e Get-Content .\\Dockerfile\nFROM ubuntu:18.04\n\nSHELL [\"/bin/bash\", \"-o\", \"pipefail\", \"-c\"]\n\nRUN apt-get update \\\n    \u0026\u0026 apt-get install -y --no-install-recommends curl=7.* ca-certificates=* \\\n    \u0026\u0026 apt-get clean \\\n    \u0026\u0026 rm -rf /var/lib/apt/lists/*\n\nRUN update-ca-certificates\n\nRUN curl -sL https://get.docker.com/ | sh\n\nRUN curl -LO https://storage.googleapis.com/container-structure-test/v1.8.0/container-structure-test-linux-amd64 \\\n    \u0026\u0026 chmod +x container-structure-test-linux-amd64 \\\n    \u0026\u0026 mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test\n\nVOLUME /configs\n\nENTRYPOINT [ \"/usr/local/bin/container-structure-test\" ]\n```\n##### Listing 1: Example Dockerfile\n\n### Building an image from Dockerfile\nTo build an image based on a Dockerfile, use the Invoke-DockerBuild CmdLet, like so:\n\n```powershell\nPS C:\\docker\u003e Invoke-DockerBuild . -ImageName structure\nSending build context to Docker daemon  4.608kB\n\nStep 1/8 : FROM ubuntu:18.04\n ---\u003e 775349758637\nStep 2/8 : SHELL [\"/bin/bash\", \"-o\", \"pipefail\", \"-c\"]\n ---\u003e Using cache\n ---\u003e b3d8c49615a7\nStep 3/8 : RUN apt-get update     \u0026\u0026 apt-get install -y --no-install-recommends curl=7.* ca-certificates=*     \u0026\u0026 apt-get clean     \u0026\u0026 rm -rf /var/lib/apt/lists/*\n ---\u003e Using cache\n ---\u003e 9470f9c9ecea\nStep 4/8 : RUN update-ca-certificates\n ---\u003e Using cache\n ---\u003e 80853c222946\nStep 5/8 : RUN curl -sL https://get.docker.com/ | sh\n ---\u003e Using cache\n ---\u003e af17b9b8fb1b\nStep 6/8 : RUN curl -LO https://storage.googleapis.com/container-structure-test/v1.8.0/container-structure-test-linux-amd64     \u0026\u0026 chmod +x container-structure-test-linux-amd64     \u0026\u0026 mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test\n ---\u003e Using cache\n ---\u003e bea1dca8e10e\nStep 7/8 : VOLUME /configs\n ---\u003e Using cache\n ---\u003e 97e90bf8481b\nStep 8/8 : ENTRYPOINT [ \"/usr/local/bin/container-structure-test\" ]\n ---\u003e Using cache\n ---\u003e 6b9746ab76d8\nSuccessfully built 6b9746ab76d8\nSuccessfully tagged structure:latest\nSECURITY WARNING: You are building a Docker image from Windows against a non-Windows Docker host. All files and directories added to build context will have '-rwxr-xr-x' permissions. It is recommended to double check and reset permissions for sensitive files and directories.\n\nDockerfile    : Dockerfile\nImageName     : structure\nRegistry      :\nTag           : latest\nCommandResult : CommandResult\n```\n##### Listing 2: Output from building a docker image\n\nIn this scenario, you will see the both the output from Docker and the result of the execution which is a PSCustomObject that holds:\n\n- The path to the Dockerfile being used as the basis for the image.\n- The name of the image being produced.\n- The registry (if unset defaults to Docker's default registry)\n- The command result object which has more detailed information about the execution.\n\nIn most cases you will want to store the result in a variable for further processing or output to a CI/CD pipeline, like so:\n\n```powershell\nPS C:\\docker\u003e Invoke-DockerBuild . -ImageName structure\nSending build context to Docker daemon  4.608kB\n\nStep 1/8 : FROM ubuntu:18.04\n ---\u003e 775349758637\nStep 2/8 : SHELL [\"/bin/bash\", \"-o\", \"pipefail\", \"-c\"]\n ---\u003e Using cache\n ---\u003e b3d8c49615a7\nStep 3/8 : RUN apt-get update     \u0026\u0026 apt-get install -y --no-install-recommends curl=7.* ca-certificates=*     \u0026\u0026 apt-get clean     \u0026\u0026 rm -rf /var/lib/apt/lists/*\n ---\u003e Using cache\n ---\u003e 9470f9c9ecea\nStep 4/8 : RUN update-ca-certificates\n ---\u003e Using cache\n ---\u003e 80853c222946\nStep 5/8 : RUN curl -sL https://get.docker.com/ | sh\n ---\u003e Using cache\n ---\u003e af17b9b8fb1b\nStep 6/8 : RUN curl -LO https://storage.googleapis.com/container-structure-test/v1.8.0/container-structure-test-linux-amd64     \u0026\u0026 chmod +x container-structure-test-linux-amd64     \u0026\u0026 mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test\n ---\u003e Using cache\n ---\u003e bea1dca8e10e\nStep 7/8 : VOLUME /configs\n ---\u003e Using cache\n ---\u003e 97e90bf8481b\nStep 8/8 : ENTRYPOINT [ \"/usr/local/bin/container-structure-test\" ]\n ---\u003e Using cache\n ---\u003e 6b9746ab76d8\nSuccessfully built 6b9746ab76d8\nSuccessfully tagged structure:latest\nSECURITY WARNING: You are building a Docker image from Windows against a non-Windows Docker host. All files and directories added to build context will have '-rwxr-xr-x' permissions. It is recommended to double check and reset permissions for sensitive files and directories.\n```\n##### Listing 3: Build docker image and store result in variable.\n\nin which case you will only see the output from Docker, the result object is stored in $result.\n\nYou can verify the existence of the image you just created using `docker images`\n```\nPS C:\\docker\u003e docker images\n```\n\nIf you want less output, use `-Quiet` switch to output only the final result of the command. Combined with storing the result in a variable, this will give a completely silent execution of the CmdLet.\n\n### Disabling verbose output\nThe -Quiet setting for CmdLets that support it, defaults to the value of the enviromenment variable `DOCKER_CI_QUIET_MODE`.\nSo you can set this environment variable to the desired setting for the `-Quiet` switch so you don't have to set it for each invocation of a cmdlet that supports it.\n\n### Linting a Dockerfile\nAn important aspect of writing quality Docker images is to try and learn from the best in the community. To this end, we provide a convenient way to run `hadolint` against a Dockerfile. Hadolint is a 3rd party component that scans a dockerfile and produces linted output. You can find the hadolint project here: https://github.com/hadolint/hadolint\n\nHere's how to use the linter via a CmdLet:\n\n```powershell\nPS C:\\docker\u003e $result = Invoke-DockerLint .\\Dockerfile\n1: FROM ubuntu:18.04\n2:\n3: SHELL [\"/bin/bash\", \"-o\", \"pipefail\", \"-c\"]\n4:\n5: RUN apt-get update \\\n6:     \u0026\u0026 apt-get install -y --no-install-recommends curl=7.* ca-certificates=* \\\n7:     \u0026\u0026 apt-get clean \\\n8:     \u0026\u0026 rm -rf /var/lib/apt/lists/*\n9:\n10: RUN update-ca-certificates\n11:\n12: RUN curl -sL https://get.docker.com/ | sh\n13:\n14: RUN curl -LO https://storage.googleapis.com/container-structure-test/v1.8.0/container-structure-test-linux-amd64 \\\n15:     \u0026\u0026 chmod +x container-structure-test-linux-amd64 \\\n16:     \u0026\u0026 mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test\n17:\n18: VOLUME /configs\n19:\n20: ENTRYPOINT [ \"/usr/local/bin/container-structure-test\" ]\n```\n##### Listing 4: Build docker image and store result in variable.\n\nThis Dockerfile in particular has no linting remarks, so it is just output in its entirety with line numbers. Imagine I omitted the instruction in line 3 on how to deal with commands that fail in a piped execution and run the linting again:\n\n```powershell\nPS C:\\docker\u003e $result = Invoke-DockerLint .\\Dockerfile\n1: FROM ubuntu:18.04\n2:\n3: RUN apt-get update \\\n4:     \u0026\u0026 apt-get install -y --no-install-recommends curl=7.* ca-certificates=* \\\n5:     \u0026\u0026 apt-get clean \\\n6:     \u0026\u0026 rm -rf /var/lib/apt/lists/*\n7:\n8: RUN update-ca-certificates\n9:\nDL4006 Set the SHELL option -o pipefail before RUN with a pipe in it\n10: RUN curl -sL https://get.docker.com/ | sh\n11:\n12: RUN curl -LO https://storage.googleapis.com/container-structure-test/v1.8.0/container-structure-test-linux-amd64 \\\n13:     \u0026\u0026 chmod +x container-structure-test-linux-amd64 \\\n14:     \u0026\u0026 mv container-structure-test-linux-amd64 /usr/local/bin/container-structure-test\n15:\n16: VOLUME /configs\n17:\n18: ENTRYPOINT [ \"/usr/local/bin/container-structure-test\" ]\n```\n##### Listing 5: Lint docker file and store result in variable\n\nNow, the linter is no longer happy and it has added a remark just above line 10 instructing us on how to fix the problem. The first part of the message is a unique lint rule id that can be used to find the lint rationale and in-depth explanation on https://github.com/hadolint/hadolint.\n\n#### Failing the build when there are lint remarks\nIn CI/CD contexts, you might want to fail a build or similar, if there are linting errors. Raising an exception when there are lint remarks found is straigt-forward:\n\n```\nInvoke-DockerLint -TreatLintRemarksFoundAsException\n```\n\nGoing from the example Dockerfile in listing 5, we achieve an error:\n```powershell\nPS C:\\docker\u003e $result = Invoke-DockerLint -TreatLintRemarksFoundAsException\nAssert-ExitCodeOk : The command 'Get-Content \"C:\\docker\\Dockerfile\" | docker run -i hadolint/hadolint:v1.17.2' failed with exit code: 1.\nCommand output:\n/dev/stdin:10 DL4006 Set the SHELL option -o pipefail before RUN with a pipe in it\nAt C:\\Users\\Rasmus Jelsgaard\\Documents\\PowerShell\\Modules\\Docker-CI\\0.4.8\\Public\\Invoke-DockerLint.ps1:31 char:9\n+         Assert-ExitCodeOk $commandResult\n+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo          : InvalidResult: (:) [Assert-ExitCodeOk], Exception\n+ FullyQualifiedErrorId : 1000,Assert-ExitCodeOk\n\nPS C:\\docker\u003e $LASTEXITCODE\n1\n```\n##### Listing 6: Fail execution if there are lint remarks.\n\nIf you would rather only fail once a certain threshold is met, you can do something like this to that effect (again based on the Dockerfile in listing 5):\n\n```powershell\nPS C:\\docker\u003e $result = Invoke-DockerLint -Quiet\nPS C:\\docker\u003e $result.LintRemarks.Length -gt 0\nTrue\n```\n\nThis concludes the examples on linting. Whilst linting can help you improve parts of your Docker-style and quality of the images, it is no substitute for real testing.\n\n### Testing a docker image\nWe provide testing of docker images using Google's Container Structure framework (https://github.com/GoogleContainerTools/container-structure-test).\n\nTo run tests, you first define them in .yml configs. Then you build the image the image you want to test, and then finally you run the tests.\n\nSo let's start by building an image called `structure`\n\n```powershell\nPS C:\\docker\u003e Invoke-DockerBuild . -Quiet -ImageName structure\n\nDockerfile    : Dockerfile\nImageName     : structure\nRegistry      :\nTag           : latest\nCommandResult : CommandResult\n```\n\nThen, we define a test to check if the correct binary was produced and placed in accordance with the documentation at https://github.com/GoogleContainerTools/container-structure-test.\n\nThe config file gcs-commands.yml looks like this:\n\n```yml\nschemaVersion: \"2.0.0\"\n\ncommandTests:\n  - name: \"say hello world\"\n    command: \"bash\"\n    args:\n      - -c\n      - |\n        echo hello \u0026\u0026\n        echo world\n    exitCode: 0\n    expectedOutput: [\"hello\", \"world\"]\n```\n\nAnd you run the tests like this:\n\n```powershell\nPS C:\\docker\u003e $result = Invoke-DockerTests -ImageName 3shape/containerized-structure-test -ConfigFiles gcs-commands.yml\n@{Pass=1; Fail=0; Total=1; Results=System.Object[]}\nPS C:\\docker\u003e $result\n\nTestResult                                          TestReportPath            CommandResult ImageName\n----------                                          --------------            ------------- ---------\n@{Pass=1; Fail=0; Total=1; Results=System.Object[]} C:\\docker\\testreport.json CommandResult 3shape/containerized-structure-test\n```\n\nThis concludes the section with examples. Let us know if there is something missing, that is not clear from the documentation.\n\n# Development environment setup\n* Install PowerShell Core 6.x or newer.\n* Run `.\\Install-Prerequisites.ps1`\n","funding_links":[],"categories":["PowerShell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3shape%2Fdocker-ci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F3shape%2Fdocker-ci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3shape%2Fdocker-ci/lists"}