Skip to content
This repository was archived by the owner on Aug 30, 2021. It is now read-only.

Commit c1290d4

Browse files
matootiematootie
authored
Include support for GitHub Container Registry (#21)
You can now use GitHub Docker for either the GitHub Package Registry or the GitHub Container Registry
1 parent 310af4a commit c1290d4

File tree

7 files changed

+376
-58
lines changed

7 files changed

+376
-58
lines changed

‎.github/workflows/CI.yml

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ jobs:
1717
- name: Checkout repository
1818
uses: actions/checkout@v2
1919

20-
- name: Run the action
20+
- name: Run the action with Package Registry
2121
uses: ./
22-
id: publish
22+
id: publish-ghpr
2323
with:
2424
accessToken: ${{ github.token }}
2525
imageName: action-test
@@ -31,3 +31,19 @@ jobs:
3131
TESTARG2=test2
3232
context: test/
3333
contextName: test.Dockerfile
34+
35+
- name: Run the action with Container Registry
36+
uses: ./
37+
id: publish-ghcr
38+
with:
39+
accessToken: ${{ secrets.PAT }}
40+
imageName: github-docker-test
41+
tag: |
42+
latest-${{ matrix.os }}
43+
test-${{ matrix.os }}
44+
buildArgs: |
45+
TESTARG1=test1
46+
TESTARG2=test2
47+
context: test/
48+
contextName: test.Dockerfile
49+
containerRegistry: true

‎README.md

Lines changed: 145 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,42 @@
11
# GitHub Docker Action
22

3-
Build and publish your repository as a Docker image and push it to GitHub Package Registry in one easy step.
3+
Build and publish your repository as a Docker image and push it to GitHub Package Registry or GitHub Container Registry in one easy step.
44

55
[![GitHub Release](https://img.shields.io/github/v/release/matootie/github-docker)](https://github.com/matootie/github-docker/releases/latest)
66

7-
For help updating, view the [change logs](https://github.com/matootie/github-docker/releases).
7+
For help updating, view the [change logs](https://github.com/matootie/github-docker/releases). If you need additional help feel free to submit an issue.
8+
9+
## Table of Contents
10+
11+
- [**Inputs**](#inputs)
12+
- [**Outputs**](#outputs)
13+
- [**GitHub Package Registry**](#github-package-registry-usage)
14+
- [Simple usage](#simple-minimal-usage)
15+
- [Custom tag](#publishing-using-custom-tag)
16+
- [Multiple tags](#publishing-using-several-tags)
17+
- [Build arguments](#publishing-using-build-arguments)
18+
- [Using output](#publishing-and-using-output)
19+
- [Custom context](#publishing-using-custom-context)
20+
- [Publishing to a different repository](#publishing-to-a-different-repository)
21+
- [**GitHub Container Registry**](#github-container-registry-usage)
22+
- [Simple usage](#simple-minimal-usage-1)
23+
- [Custom tag](#publishing-using-custom-tag-1)
24+
- [Multiple tags](#publishing-using-several-tags-1)
25+
- [Build arguments](#publishing-using-build-arguments-1)
26+
- [Using output](#publishing-and-using-output-1)
27+
- [Custom context](#publishing-using-custom-context-1)
828

929
## Inputs
1030

1131
| Name | Requirement | Description |
1232
| --------------------- | ----------------- | ------------|
13-
| `accessToken` | **Required** | GitHub Repository Token to log in using. Must have write permissions for packages. Recommended set up would be to use the provided GitHub Token for your repository; `${{ github.token }}`.
33+
| `accessToken` | **Required** | GitHub Access Token to log in using. Must have write permissions for packages. Recommended set up would be to use the provided GitHub Token for your repository; `${{ github.token }}`.
1434
| `imageName` | ***Optional*** | The desired name for the image. Defaults to current repository name.
1535
| `tag` | ***Optional*** | The desired tag for the image. Defaults to `latest`. Optionally accepts multiple tags separated by newline. _See [example below](#publishing-using-several-tags)_.
1636
| `buildArgs` | ***Optional*** | Any additional build arguments to use when building the image, separated by newline. _See [example below](#publishing-using-build-arguments)_.
1737
| `context` | ***Optional*** | Where should GitHub Docker find the Dockerfile? This is a path relative to the repository root. Defaults to `.`, meaning it will look for a `Dockerfile` in the root of the repository. _See [example below](#publishing-using-custom-context)_.
1838
| `contextName` | ***Optional*** | What Dockerfile should GitHub Docker be using when building. Defaults to traditional `Dockerfile` name. _See [example below](#publishing-using-custom-context)_.
39+
| `containerRegistry` | ***Optional*** | Whether or not to push to GitHub Container Registry instead of GitHub Package Registry. _When using GitHub Container Registry there are a few important differences to keep in mind. See [explanation below](#github-container-registry-usage)_.
1940
| `repository` | ***Optional*** | The repository to push the image to. Defaults to the current repository. Must be specified in format `user/repo`. _Note: Using an external repository requires elevated permissions. The provided GitHub token for the repository running the action will **not** suffice. You must use custom secret containing a [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) that has package write permissions on the given repository. See [example below](#publishing-to-a-different-repository)_.
2041

2142
## Outputs
@@ -24,26 +45,26 @@ For help updating, view the [change logs](https://github.com/matootie/github-doc
2445
| --------------------- | ------------------------------------------ |
2546
| `imageURL` | The URL of the image, **without** the tag. |
2647

27-
## Example usage
48+
## GitHub Package Registry usage
2849

2950
#### Simple, minimal usage...
3051

3152
```yaml
3253
- name: Publish Image
33-
uses: matootie/github-docker@v3.0.0
54+
uses: matootie/github-docker@v3.1.0
3455
with:
3556
accessToken: ${{ github.token }}
3657
```
3758
38-
That's right this is all you need to get started with GitHub Docker, simply provide the GitHub token and the defaults will go to work. An image following the repository name will be pushed to the repository, with a tag corresponding to the commit SHA that triggered the workflow. The resulting URL is set as output for easy use in future steps!
59+
That's right this is all you need to get started with GitHub Docker, simply provide the GitHub token and the defaults will go to work. An image following the repository name will be pushed to the repository, tagged with `latest`. The resulting URL is set as output for easy use in future steps!
3960

4061
For additional customizations, see further examples below. For more information on the output URL, see [this example](#publishing-and-using-output).
4162

4263
#### Publishing using custom tag...
4364

4465
```yaml
4566
- name: Publish Image
46-
uses: matootie/github-docker@v3.0.0
67+
uses: matootie/github-docker@v3.1.0
4768
with:
4869
accessToken: ${{ github.token }}
4970
tag: latest
@@ -55,7 +76,7 @@ In this example we specify a custom tag for the image. Remember to append the ta
5576

5677
```yaml
5778
- name: Publish Image
58-
uses: matootie/github-docker@v3.0.0
79+
uses: matootie/github-docker@v3.1.0
5980
with:
6081
accessToken: ${{ github.token }}
6182
tag: |
@@ -69,7 +90,7 @@ In this example we publish the same image under two different tags.
6990

7091
```yaml
7192
- name: Publish Image
72-
uses: matootie/github-docker@v3.0.0
93+
uses: matootie/github-docker@v3.1.0
7394
with:
7495
accessToken: ${{ github.token }}
7596
buildArgs: |
@@ -83,7 +104,7 @@ Using build arguments is easy, just set each one on its own individual line, sim
83104

84105
```yaml
85106
- name: Publish Image
86-
uses: matootie/github-docker@v3.0.0
107+
uses: matootie/github-docker@v3.1.0
87108
id: publish
88109
with:
89110
accessToken: ${{ github.token }}
@@ -96,7 +117,7 @@ In this example you can see how easy it is to reference the image URL after publ
96117

97118
```yaml
98119
- name: Publish Image
99-
uses: matootie/github-docker@v3.0.0
120+
uses: matootie/github-docker@v3.1.0
100121
id: publish
101122
with:
102123
accessToken: ${{ github.token }}
@@ -112,7 +133,7 @@ Otherwise, future steps will end up using the literal tag `latest` for the image
112133

113134
```yaml
114135
- name: Publish Image
115-
uses: matootie/github-docker@v3.0.0
136+
uses: matootie/github-docker@v3.1.0
116137
with:
117138
accessToken: ${{ github.token }}
118139
context: custom/context/dir/
@@ -125,10 +146,121 @@ Here we see an example where GitHub Docker is given additional context on how to
125146

126147
```yaml
127148
- name: Publish Image
128-
uses: matootie/github-docker@v3.0.0
149+
uses: matootie/github-docker@v3.1.0
129150
with:
130151
accessToken: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
131152
repository: my-user/my-repo
132153
```
133154

134155
In this example we're pushing the resulting image to be listed under a separate repository, different from the one that this action is running on. Remember, in this case the provided `${{ github.token }}` will **not** work as it only has the necessary permissions for its own repository. You need to save a GitHub [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) with write permissions to packages as a secret, and use that.
156+
157+
## GitHub Container Registry usage
158+
159+
Using GitHub Docker with the GitHub Container Registry is just about the same as using it with the Package Registry, but there are a few things to remember.
160+
161+
1. The `accessToken` input must be a [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) with `write:packages` scope.
162+
2. The `repositoryName` input is entirely useless as the container will be pushed to the owner of the current repository instead.
163+
164+
The following are a copy of the same examples listed above, using GitHub Container Registry instead of GitHub Package Registry. _Note the differences in input_.
165+
166+
#### Simple, minimal usage...
167+
168+
```yaml
169+
- name: Publish Image
170+
uses: matootie/github-docker@v3.1.0
171+
with:
172+
accessToken: ${{ secrets.PAT }}
173+
containerRegistry: true
174+
```
175+
176+
That's right this is all you need to get started with GitHub Docker, simply provide the GitHub token and the defaults will go to work. An image following the repository name will be pushed to the repository owner, tagged with `latest`. The resulting URL is set as output for easy use in future steps!
177+
178+
For additional customizations, see further examples below. For more information on the output URL, see [this example](#publishing-and-using-output-1).
179+
180+
#### Publishing using custom tag...
181+
182+
```yaml
183+
- name: Publish Image
184+
uses: matootie/github-docker@v3.1.0
185+
with:
186+
accessToken: ${{ secrets.PAT }}
187+
tag: latest
188+
containerRegistry: true
189+
```
190+
191+
In this example we specify a custom tag for the image. Remember to append the tag when using the outputted image URL in the workflow. See [this example](#publishing-and-using-output-1) for more details.
192+
193+
#### Publishing using several tags...
194+
195+
```yaml
196+
- name: Publish Image
197+
uses: matootie/github-docker@v3.1.0
198+
with:
199+
accessToken: ${{ secrets.PAT }}
200+
tag: |
201+
latest
202+
${{ github.sha }}
203+
containerRegistry: true
204+
```
205+
206+
In this example we publish the same image under two different tags.
207+
208+
#### Publishing using build arguments...
209+
210+
```yaml
211+
- name: Publish Image
212+
uses: matootie/github-docker@v3.1.0
213+
with:
214+
accessToken: ${{ secrets.PAT }}
215+
buildArgs: |
216+
ENVIRONMENT=test
217+
SOME_OTHER_ARG=yes
218+
containerRegistry: true
219+
```
220+
221+
Using build arguments is easy, just set each one on its own individual line, similarly to how you would in a `.env` file.
222+
223+
#### Publishing and using output...
224+
225+
```yaml
226+
- name: Publish Image
227+
uses: matootie/github-docker@v3.1.0
228+
id: publish
229+
with:
230+
accessToken: ${{ secrets.PAT }}
231+
containerRegistry: true
232+
233+
- name: Print Image URL
234+
run: echo ${{ steps.publish.outputs.imageURL }}
235+
```
236+
237+
In this example you can see how easy it is to reference the image URL after publishing. If you are using a custom tag, you most likely are going to need to append the tag to the URL when using it in the workflow...
238+
239+
```yaml
240+
- name: Publish Image
241+
uses: matootie/github-docker@v3.1.0
242+
id: publish
243+
with:
244+
accessToken: ${{ secrets.PAT }}
245+
tag: ${{ github.sha }}
246+
containerRegistry: true
247+
248+
- name: Print Full Image URL
249+
run: echo ${{ stets.publish.outputs.imageURL }}:${{ github.sha }}
250+
```
251+
252+
Otherwise, future steps will end up using the literal tag `latest` for the image and not the customized tag.
253+
254+
#### Publishing using custom context...
255+
256+
```yaml
257+
- name: Publish Image
258+
uses: matootie/github-docker@v3.1.0
259+
with:
260+
accessToken: ${{ secrets.PAT }}
261+
context: custom/context/dir/
262+
contextName: custom.Dockerfile
263+
containerRegistry: true
264+
```
265+
266+
Here we see an example where GitHub Docker is given additional context on how to find the right Dockerfile. `context` is used to specify the directory of the Dockerfile, and `contextName` is used if the name of the Dockerfile is something that different than what `docker build .` would find.

‎action.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ inputs:
2222
description: "What Dockerfile should GitHub Docker be using when building. Defaults to traditional Dockerfile name."
2323
required: false
2424
default: Dockerfile
25+
containerRegistry:
26+
description: "Whether or not to push to GitHub Container Registry instead of GitHub Package Registry."
27+
required: false
28+
default: "false"
2529
repository:
2630
description: "The repository to push the image to. Defaults to the current repository. Must be specified in format user/repo."
2731
required: false

0 commit comments

Comments
 (0)