-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.md
147 lines (99 loc) · 6.98 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
# Docker Bump GitHub Action
A [GitHub action](https://docs.github.com/actions) that can be used to trigger a GitHub Actions workflow or GitHub App webhook whenever a target Docker image is not up-to-date with its dependent base image. The canonical scenario is to trigger a GitHub Actions workflow to run that will rebuild a Docker image whenever its base image has been updated. But you're free to define whatever logic you want to have executed when this out-of-date condition occurs.
This is implemented by using the [`repository-dispatch` GitHub action](https://github.com/peter-evans/repository-dispatch) to create [`repository_dispatch`](https://docs.github.com/rest/repos/repos#create-a-repository-dispatch-event) events. These events can then be responded to by a GitHub Actions workflow or GitHub App webhook.
It sounds complicated but it's actually easy to set up.
## Usage
Dispatch an event to the current repository whenever `ghcr.io/mthalman/docker-bump-action-example:latest` is not up-to-date with `alpine:latest`.
```yml
name: Monitor for Base Image Update
on:
schedule:
- cron: "0 2 * * *"
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: mthalman/docker-bump-action@v0
with:
target-image-name: ghcr.io/mthalman/docker-bump-action-example:latest
dockerfile: Dockerfile
```
Add the following in the workflow which builds your Docker image:
```yml
on:
repository_dispatch:
types: [base-image-update]
```
See a working example of these workflows at [mthalman/docker-bump-action-example](https://github.com/mthalman/docker-bump-action-example).
See [Examples](#examples) below for more usage patterns.
### Action inputs
| Name | Description | Default |
| --- | --- | --- |
| `target-image-name` |**Required** Name of the image to check. | |
| `base-image-name` | Name of the base image the target image is based on. **Required** when `dockerfile` is not set. See [Image Name Derivation](#base-image-name-derivation). | |
| `dockerfile` | Path to the Dockerfile from which to derive image names. **Required** when `base-image-name` is not set. See [Image Name Derivation](#base-image-name-derivation). | |
| `base-stage-name` | Name of the stage within the Dockerfile from which to derive the name of the base image. See [Image Name Derivation](#base-image-name-derivation). | |
| `arch` | Default architecture of the image | `amd64` |
| `repository` | The full name of the repository to send the dispatch. | `${{ github.repository }}` |
| `event-type` | A custom webhook event name. | `base-image-update` |
| `token` | An access token with the appropriate permissions. See [Token](#token). | `${{ github.token }}` |
## OS Support
Support is limited to Linux container images only.
## Token
In order to create the [`repository_dispatch`](https://docs.github.com/rest/repos/repos#create-a-repository-dispatch-event) events, the action requires access to the repo via a token.
The default `GITHUB_TOKEN` token can only be used if you are dispatching to the same repository that the workflow is executing in.
To dispatch to a separate repository you must create a [personal access token (PAT)](https://docs.github.com/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with the `repo` scope and [store it as a secret](https://docs.github.com/actions/security-guides/using-secrets-in-github-actions). If you will be dispatching to a public repository then you can use the more limited `public_repo` scope.
You can also use a fine-grained personal access token (beta). It needs the following permissions on the target repositories:
* `contents: read & write`
* `metadata: read only` (automatically selected when selecting the contents permission)
## Base Image Name Derivation
The base image name can either be provided explicitly via the `base-image-name` input or can be derived from the content of the Dockerfile specified by the `dockerfile` input. Be sure to examine the log output from the action to verify which image name it is using.
Depending on how you've structured your Dockerfiles (specifically for multi-stage Dockerfiles), the base image name that is derived by the algorithm may not be what you intended. If the base image name is not what you intended, you can override it via the `base-image-name` or `base-stage-name` inputs.
The algorithm for deriving the image names is described below:
1. Find the last stage defined in the Dockerfile.
1. Starting from the last stage, walk the stage hierarchy until the root stage is found.
1. The image name of the root stage is considered the base image name.
## Examples
### Explicitly set base stage name
In this example, the test stage is the last stage listed.
Based on the [algorithm described above](#base-image-name-derivation), the action would start at the last stage and walk the hierarchy until it reached the root stage, which has an image name of `mcr.microsoft.com/dotnet/sdk:latest`.
That's what would be used as the base image name. However, that's not what we want since the actually shipping app image is based on `mcr.microsoft.com/dotnet/runtime:latest`.
```Dockerfile
# Build image
FROM mcr.microsoft.com/dotnet/sdk:latest AS build
<content>
# App image
FROM mcr.microsoft.com/dotnet/runtime:latest AS app
COPY --from=build /app /app
# Test image
FROM build AS test
<content>
```
To configure the action to use `mcr.microsoft.com/dotnet/runtime:latest` as the base image name, the `base-stage-name` input is set to `app`.
```yaml
- uses: mthalman/docker-bump-action@v0
with:
target-image-name: ghcr.io/mthalman/docker-bump-action-example:latest
base-stage-name: app
```
Indicating the base **stage** name rather than the base **image** name can be more convenient because it allows the image name in the Dockerfile to be updated without needing to also change the workflow file.
### Explicitly set base image name
In this example, the base image name used in the Dockerfile is dynamic so the action can't use the Dockerfile as input.
```Dockerfile
ARG BASE_IMAGE
FROM $BASE_IMAGE
<rest of content>
```
Instead, the desired base image name is explicitly provided as input.
Here, the base image name is explicitly set to `alpine:latest`.
```yaml
- uses: mthalman/docker-bump-action@v0
with:
target-image-name: ghcr.io/mthalman/docker-bump-action-example:latest
base-image-name: alpine:latest
```
## Troubleshooting
### Error: `Resource not accessible by integration`
This error occurs when using the `GITHUB_TOKEN` token (the default token value) and not having write permissions for the repo. Go to your GitHub repo's Settings page at `https://github.com/<owner>/<repo>/settings/actions` and ensure that `Read and write permissions` is set for Workflow permissions.
### Error: `Repository not found, OR token has insufficient permissions.`
This error occurs when the [personal access token (PAT)](https://docs.github.com/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) is not configured with appropriate permissions. See [Token](#token) for configuration details.