From b9dd5932a8f3bc7b92da3312293f86ccb454fced Mon Sep 17 00:00:00 2001 From: Nick Adcock Date: Thu, 5 Mar 2020 16:28:11 +0000 Subject: [PATCH] Add inputs and examples to readme Signed-off-by: Nick Adcock --- README.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++- action.yml | 4 +- 2 files changed, 191 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 472756c..712eb4f 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,190 @@ # build-push-action -Build+push official Docker GitHub action + +Builds and pushes docker images and will log in to a docker registry if required + +[Inputs](#Inputs) +* [repository](#repository) +* [username](#username) +* [password](#password) +* [registry](#registry) +* [tags](#tags) +* [tag_with_ref](#tag_with_ref) +* [tag_with_sha](#tag_with_sha) +* [path](#path) +* [dockerfile](#dockerfile) +* [target](#target) +* [always_pull](#always_pull) +* [build_args](#build_args) +* [labels](#labels) +* [add_git_labels](#add_git_labels) +* [push](#push) + +[Example usage](#Example-usage) + +## Inputs + +### `repository` + +**Required** Docker repository to tag the image with. + +### `username` + +Username used to log in to a docker registry. If not set then no login will occur. + +### `password` + +Password used to log in to a docker registry. If not set then no login will occur. + +### `registry` + +Server address of docker registry. If not set then will default to Docker Hub. + +### `tags` + +Comma-delimited list of tags. These will be added to the registry/repository to form the image's tags. + +Example: + +```yaml +tags: tag1,tag2 +``` + +### `tag_with_ref` + +Boolean value. Defaults to `false`. + +Automatically tags the built image with the git reference. The format of the tag depends on the type of git reference with all forward slashes replaced with `-`. + +For pushes to a branch the reference will be `refs/heads/{branch-name}` and the tag will be `{branch-name}`. If `{branch-name}` is master then the tag will be `latest`. + +For pull requests the reference will be `refs/pull/{pull-request}` and the tag will be `pr-{pull-request}`. + +For git tags the reference will be `refs/tags/{git-tag}` and the tag will be `{git-tag}`. + +Examples: + +|Git Reference|Image tag| +|---|---| +|`refs/heads/master`|`latest`| +|`refs/heads/my/branch`|`my-branch`| +|`refs/pull/2/merge`|`pr-2-merge`| +|`refs/tags/v1.0.0`|`v1.0.0`| + +### `tag_with_sha` + +Boolean value. Defaults to `false`. + +Automatically tags the built image with the git short sha prefixed with `sha-`. + +Example: + +|Git sha|Image tag| +|---|---| +|`676cae2f85471aeff6776463c72881ebd902dcf9`|`sha-676cae2`| + +### `path` + +Path to run the docker build from. Defaults to `.`. + +### `dockerfile` + +Name of the Dockerfile (Default is 'path/Dockerfile'). Defaults to `{path}/Dockerfile`. + +### `target` + +Sets the target build stage to build. + +### `always_pull` + +Boolean value. Defaults to `false`. + +Always attempt to pull a newer version of the image. + +### `build_args` + +Comma-delmited list of build-time variables. + +Example: + +```yaml +build_args: arg1=value1,arg2=value2 +``` + +### `labels` + +Comma-delimited list of labels to add to the built image. + +Example: + +```yaml +labels: label_name_1=label_value_1,label_name_2=label_value_2 +``` + +### `add_git_labels` + +Boolean value. Defaults to `false`. + +Adds labels with git repo info to the built image. + +The labels are: + +|Label key|Example value|Description| +|---|---|---| +|`com.docker.github-actions-actor`|`my-username`|The actor that kicked off the workflow. For example this could be the username of the user that did the git push.| +|`com.docker.github-actions-sha`|`676cae2f85471aeff6776463c72881ebd902dcf9`|Full git sha of the current commit.| + + +### `push` + +Boolean value. Defaults to `true`. + +Whether to push the built image. + +## Example usage + +The following will build the root Dockerfile, tag the image as `myorg/myrepository:latest`, logs in to docker hub using GitHub secrets, and pushes the image to the docker hub repository `myorg/myrepository`: + +```yaml +uses: docker/build-push-action@v1 +with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + repository: myorg/myrepository + tags: latest +``` + +The following will build the root Dockerfile, tag the image with the git reference and sha as described above, logs in to docker hub using GitHub secrets, and pushes the image to the docker hub repository `myorg/myrepository`: + +```yaml +uses: docker/build-push-action@v1 +with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + repository: myorg/myrepository + tag_with_ref: true + tag_with_sha: true +``` + +The following will only push the image when the event that kicked off the workflow was a push of a git tag: + +```yaml +uses: docker/build-push-action@v1 +with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + repository: myorg/myrepository + tag_with_ref: true + push: ${{ startsWith(github.ref, 'refs/tags/') }} +``` + +The following builds the `mytarget` stage and pushes that: + +```yaml +uses: docker/build-push-action@v1 +with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + repository: myorg/myrepository + tag_with_ref: true + target: mytarget +``` \ No newline at end of file diff --git a/action.yml b/action.yml index af273a4..7e5cb5c 100644 --- a/action.yml +++ b/action.yml @@ -20,7 +20,7 @@ inputs: description: Docker repository to tag the image with required: true tags: - description: Comma-delimited list of tags. These will be added to the server/repository to form the image's tags + description: Comma-delimited list of tags. These will be added to the registry/repository to form the image's tags required: false tag_with_ref: description: Automatically tags the built image with the git reference as per the readme @@ -48,7 +48,7 @@ inputs: description: Comma-delmited list of build-time variables required: false labels: - description: Comma-delimited list of labels to add to the built image. E.g. `label_name_1=label_value_1,label_name_2=label_value_2` + description: Comma-delimited list of labels to add to the built image required: false add_git_labels: description: Adds labels with git repo info to the built image