Merge pull request #198 from crazy-max/update-readme

Improve README
This commit is contained in:
CrazyMax 2020-10-22 23:56:32 +02:00 committed by GitHub
commit 5b4307de80
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 89 additions and 19 deletions

View file

@ -255,6 +255,29 @@ jobs:
if: always() if: always()
uses: crazy-max/ghaction-dump-context@v1 uses: crazy-max/ghaction-dump-context@v1
export-docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
uses: actions/checkout@v2.3.3
-
name: Build
uses: ./
with:
context: ./test
file: ./test/Dockerfile
load: true
tags: myimage:latest
-
name: Inspect
run: |
docker image inspect myimage:latest
-
name: Dump context
if: always()
uses: crazy-max/ghaction-dump-context@v1
multi: multi:
runs-on: ubuntu-latest runs-on: ubuntu-latest
strategy: strategy:

View file

@ -7,10 +7,10 @@
## Upgrade from v1 ## Upgrade from v1
`v2` of this action includes significant updates and now uses Docker [Buildx](https://github.com/docker/buildx). It `v2` of this action includes significant updates and now uses Docker [Buildx](https://github.com/docker/buildx). It
works with 3 new optional actions ([login](https://github.com/docker/login-action), [setup-buildx](https://github.com/docker/setup-buildx-action) works with 3 new actions ([login](https://github.com/docker/login-action), [setup-buildx](https://github.com/docker/setup-buildx-action)
and [setup-qemu](https://github.com/docker/setup-qemu-action)) that we have created. It's also rewritten as a and [setup-qemu](https://github.com/docker/setup-qemu-action)) that we have created. It's also rewritten as a
[typescript-action](https://github.com/actions/typescript-action/) to be as closed as possible of the [typescript-action](https://github.com/actions/typescript-action/) to be as closed as possible of the
[GitHub Runner](https://github.com/actions/virtual-environments) during its execution (#71 #92). [GitHub Runner](https://github.com/actions/virtual-environments) during its execution.
[Upgrade notes](UPGRADE.md) and many [usage examples](#usage) have been added to handle most use cases but `v1` is [Upgrade notes](UPGRADE.md) and many [usage examples](#usage) have been added to handle most use cases but `v1` is
still available through [`releases/v1` branch](https://github.com/docker/build-push-action/tree/releases/v1). still available through [`releases/v1` branch](https://github.com/docker/build-push-action/tree/releases/v1).
@ -37,6 +37,7 @@ ___
* [Push to multi-registries](#push-to-multi-registries) * [Push to multi-registries](#push-to-multi-registries)
* [Cache to registry](#push-to-multi-registries) * [Cache to registry](#push-to-multi-registries)
* [Local registry](#local-registry) * [Local registry](#local-registry)
* [Export image to Docker](#export-image-to-docker)
* [Leverage GitHub cache](#leverage-github-cache) * [Leverage GitHub cache](#leverage-github-cache)
* [Complete workflow](#complete-workflow) * [Complete workflow](#complete-workflow)
* [Update DockerHub repo description](#update-dockerhub-repo-description) * [Update DockerHub repo description](#update-dockerhub-repo-description)
@ -56,7 +57,8 @@ build-secrets, remote cache, etc. and different builder deployment/namespacing o
### Git context ### Git context
The default behavior of this action is to use the [Git context invoked by your workflow](https://github.com/docker/build-push-action/blob/master/src/context.ts#L31-L35). The default behavior of this action is to use the [Git context invoked](https://github.com/docker/build-push-action/blob/master/src/context.ts#L31-L35)
by your workflow.
```yaml ```yaml
name: ci name: ci
@ -380,6 +382,46 @@ For testing purposes you may need to create a [local registry](https://hub.docke
``` ```
</details> </details>
### Export image to Docker
You may want your build result to be available in the Docker client through `docker images` to be able to use it
in another step of your workflow:
<details>
<summary><b>Show workflow</b></summary>
```yaml
name: ci
on:
push:
branches: master
jobs:
export-docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
uses: actions/checkout@v2
-
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1
-
name: Build
uses: docker/build-push-action@v2
with:
context: .
file: ./Dockerfile
load: true
tags: myimage:latest
-
name: Inspect
run: |
docker image inspect myimage:latest
```
</details>
### Leverage GitHub cache ### Leverage GitHub cache
You can leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows) You can leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)
@ -427,15 +469,20 @@ using [actions/cache](https://github.com/actions/cache) with this action:
``` ```
</details> </details>
> If you want to [export layers for all stages](https://github.com/docker/buildx#--cache-tonametypetypekeyvalue),
> you have to specify `mode=max` attribute in `cache-to`.
### Complete workflow ### Complete workflow
If you come from [`v1`](https://github.com/docker/build-push-action/tree/releases/v1#readme) and you want an If you come from [`v1`](https://github.com/docker/build-push-action/tree/releases/v1#readme) and want an
"automatic" tag management through Git reference and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md) "automatic" tag management through Git reference and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
for labels, you will have to do it in a dedicated step [for now](https://github.com/docker/build-push-action/issues/116). for labels, you will have to do it in a dedicated step.
The following workflow with the `Prepare` step will generate some [outputs](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjobs_idoutputs) The following workflow with the `Prepare` step will generate some [outputs](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjobs_idoutputs)
to handle tags and labels based on GitHub actions events. This is just an example to show many cases that you to handle tags and labels based on GitHub actions events.
might want to use:
This is just an example to show many cases that you might want to use and that you will have to adapt according
to your needs:
<details> <details>
<summary><b>Show workflow</b></summary> <summary><b>Show workflow</b></summary>
@ -595,6 +642,18 @@ with this action:
Following inputs can be used as `step.with` keys Following inputs can be used as `step.with` keys
> `List` type is a newline-delimited string
> ```yaml
> cache-from: |
> user/app:cache
> type=local,src=path/to/dir
> ```
> `CSV` type is a comma-delimited string
> ```yaml
> tags: name/app:latest,name/app:1.0.0
> ```
| Name | Type | Description | | Name | Type | Description |
|---------------------|----------|------------------------------------| |---------------------|----------|------------------------------------|
| `builder` | String | Builder instance (see [setup-buildx](https://github.com/docker/setup-buildx-action) action) | | `builder` | String | Builder instance (see [setup-buildx](https://github.com/docker/setup-buildx-action) action) |
@ -615,18 +674,6 @@ Following inputs can be used as `step.with` keys
| `cache-to` | List | List of [cache export destinations](https://github.com/docker/buildx#--cache-tonametypetypekeyvalue) (eg. `type=local,dest=path/to/dir`) | | `cache-to` | List | List of [cache export destinations](https://github.com/docker/buildx#--cache-tonametypetypekeyvalue) (eg. `type=local,dest=path/to/dir`) |
| `secrets` | List | List of secrets to expose to the build (eg. `key=value`, `GIT_AUTH_TOKEN=mytoken`) | | `secrets` | List | List of secrets to expose to the build (eg. `key=value`, `GIT_AUTH_TOKEN=mytoken`) |
> `List` type is a newline-delimited string
> ```yaml
> cache-from: |
> user/app:cache
> type=local,src=path/to/dir
> ```
> `CSV` type is a comma-delimited string
> ```yaml
> tags: name/app:latest,name/app:1.0.0
> ```
### outputs ### outputs
Following outputs are available Following outputs are available