matootie/github-docker

:anchor: Build and publish your repository as a Docker image and push it to GitHub Package Registry in one step.

GitHub Docker Action

Disclaimer

I originally wrote this when GitHub Actions was very new, and the setup you had to use to push images using Docker's provided actions was not very clean. I wanted to make a one-click tool. This tool still works, however GitHub Actions has been around for a while now and Docker has really improved their provided actions. My honest recommendation to you is that you try using Docker Build-Push Action. It's what I use now. It has plenty more features, and uses Buildx. This repository will always have a place in my heart as the project that really got me into GitHub Actions.

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

For help updating, view the change logs. If you need additional help feel free to submit an issue.

Table of Contents

• Inputs
• Outputs
• GitHub Package Registry
  • Simple usage
  • Custom tag
  • Multiple tags
  • Build arguments
  • Using output
  • Custom context
  • Publishing to a different repository
• GitHub Container Registry
  • Simple usage
  • Custom tag
  • Multiple tags
  • Build arguments
  • Using output
  • Custom context

Inputs

Name	Requirement	Description
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 }}.
imageName	Optional	The desired name for the image. Defaults to current repository name.
tag	Optional	The desired tag for the image. Defaults to latest. Optionally accepts multiple tags separated by newline. See example below.
buildArgs	Optional	Any additional build arguments to use when building the image, separated by newline. See example below.
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.
contextName	Optional	What Dockerfile should GitHub Docker be using when building. Defaults to traditional Dockerfile name. See example below.
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.
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 that has package write permissions on the given repository. See example below.

Outputs

With Parameter	Description
imageURL	The URL of the image, without the tag.

GitHub Package Registry usage

Simple, minimal usage...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ github.token }}

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!

For additional customizations, see further examples below. For more information on the output URL, see this example.

Publishing using custom tag...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ github.token }}
    tag: latest

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 for more details.

Publishing using several tags...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ github.token }}
    tag: |
      latest
      ${{ github.sha }}

In this example we publish the same image under two different tags.

Publishing using build arguments...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ github.token }}
    buildArgs: |
      ENVIRONMENT=test
      SOME_OTHER_ARG=yes

Using build arguments is easy, just set each one on its own individual line, similarly to how you would in a .env file.

Publishing and using output...

- name: Publish Image
  uses: matootie/[email protected]
  id: publish
  with:
    accessToken: ${{ github.token }}

- name: Print Image URL
  run: echo ${{ steps.publish.outputs.imageURL }}    

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...

- name: Publish Image
  uses: matootie/[email protected]
  id: publish
  with:
    accessToken: ${{ github.token }}
    tag: ${{ github.sha }}

- name: Print Full Image URL
  run: echo ${{ steps.publish.outputs.imageURL }}:${{ github.sha }}

Otherwise, future steps will end up using the literal tag latest for the image and not the customized tag.

Publishing using custom context...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ github.token }}  
    context: custom/context/dir/
    contextName: custom.Dockerfile

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.

Publishing to a different repository.

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
    repository: my-user/my-repo

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 with write permissions to packages as a secret, and use that.

GitHub Container Registry usage

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.

1. The accessToken input must be a Personal Access Token with write:packages scope.
2. The repositoryName input is entirely useless as the container will be pushed to the owner of the current repository instead.

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.

Simple, minimal usage...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ secrets.PAT }}
    containerRegistry: true

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!

For additional customizations, see further examples below. For more information on the output URL, see this example.

Publishing using custom tag...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ secrets.PAT }}
    tag: latest
    containerRegistry: true

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 for more details.

Publishing using several tags...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ secrets.PAT }}
    tag: |
      latest
      ${{ github.sha }}
    containerRegistry: true

In this example we publish the same image under two different tags.

Publishing using build arguments...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ secrets.PAT }}
    buildArgs: |
      ENVIRONMENT=test
      SOME_OTHER_ARG=yes
    containerRegistry: true

Using build arguments is easy, just set each one on its own individual line, similarly to how you would in a .env file.

Publishing and using output...

- name: Publish Image
  uses: matootie/[email protected]
  id: publish
  with:
    accessToken: ${{ secrets.PAT }}
    containerRegistry: true

- name: Print Image URL
  run: echo ${{ steps.publish.outputs.imageURL }}    

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...

- name: Publish Image
  uses: matootie/[email protected]
  id: publish
  with:
    accessToken: ${{ secrets.PAT }}
    tag: ${{ github.sha }}
    containerRegistry: true

- name: Print Full Image URL
  run: echo ${{ steps.publish.outputs.imageURL }}:${{ github.sha }}

Otherwise, future steps will end up using the literal tag latest for the image and not the customized tag.

Publishing using custom context...

- name: Publish Image
  uses: matootie/[email protected]
  with:
    accessToken: ${{ secrets.PAT }}  
    context: custom/context/dir/
    contextName: custom.Dockerfile
    containerRegistry: true

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.

github-docker's Issues

How to use build arguments?

I'm not really sure how to use the optional build arguments parameter.

First, in the readme you're saying buildArguments, but in the code it's buildArg it seems like?

Second, what should be the syntax of buildArg? An example would be nice. Should it be like that:

jobs:
  publish:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

      - name: Publish Image
        uses: matootie/[email protected]
        with:
          accessToken: ${{ secrets.GITHUB_TOKEN }}
          buildArg:
            ARG1: ${{ secrets.ARG1 }}
            ARG2: ${{ secrets.ARG2 }}

EDIT: this syntax is invalid anyway so it's not that...

Or like that:

jobs:
  publish:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

      - name: Publish Image
        uses: matootie/[email protected]
        with:
          accessToken: ${{ secrets.GITHUB_TOKEN }}
          buildArg: |
            ARG1=${{ secrets.ARG1 }}
            ARG2=${{ secrets.ARG2 }}

EDIT: Also tried this, not working. It's sending all the text into a single --build-arg argument.

Or something else all together... I'm not the best with regex, so I can't really understand what's the regex is supposed to parse.

GH Package Registry requires the repository name to be lowercase when pushing it

When you are executing this line:

github-docker/index.js

Line 58 in 67591dc

['build', '--tag', `docker.pkg.github.com/${repository}/${imageName}:${imageTag}`, workspace]);

you need to force lower case on the repository name, otherwise, the action will fail.

Require even less input

It's possible to push the image as the "GitHub Actor", being the user who triggered the action to run, when the personal access token provided is the default GITHUB_TOKEN that comes with the repository.

Therefore, we can remove username as a required input.

Docker fails to find Dockerfile - weird path?

My workflow config:
https://github.com/khromov/docker-node-hello-world/blob/master/.github/workflows/main.yml

Failed build:
https://github.com/khromov/docker-node-hello-world/runs/362889904

The docker build line looks strange, specifically the path /home/runner/work/docker-node-hello-world/docker-node-hello-world. Should there really be two docker-node-hello-world folders?

Context path not applying

When attempting to run this action using the context option, the builder is still trying to locate the Dockerfile in the root of the repo. I've tried many iterations of defining that variable since the documentation doesn't state how to define it, but it always seems that the docker build command attempts to locate the Dockerfile in the root. How should the context variable be defined to properly target a Dockerfile within a subfolder?

My current config:

name: Docker Image CI
on:
  push:
    paths:
    - subdir/**
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout master branch
      uses: actions/checkout@v2
    - name: Build and push image
      uses: matootie/[email protected]
      with:
        accessToken: ${{ secrets.BUILD_TOKEN }}
        context: subdir
        repositoryName: my-org/my-repo2
        imageName: docker_image
        imageTag: latest

Last run output error:

docker build --tag docker.pkg.github.com/my-org/my-repo2/docker_image:latest /home/runner/work/my-repo/my-repo
unable to prepare context: unable to evaluate symlinks in Dockerfile path: lstat /home/runner/work/my-repo/my-repo/Dockerfile: no such file or directory

I've attempted defining conext using the iterations below with no success:

• subdir
• subdir/
• ./subdir
• ./subdir/

Security of personal access token

Hello, in the documentation example, you don't suggest using GitHub secrets:

...
# GitHub Personal Access Token for the user.
personalAccessToken: 
...

If would be better if you suggested to use a secret:

# GitHub Personal Access Token for the user. Add the token in Repo settings > Secrets
personalAccessToken: ${{ secrets.ACCESS_TOKEN }}

On another note, as I'm building using this action I get the following in my build log:

docker login docker.pkg.github.com --username khromov --password ***
WARNING! Using --password via the CLI is insecure. Use --password-stdin.
WARNING! Your password will be stored unencrypted in /home/runner/.docker/config.json.

Does this pose a risk for my token, in a way that someone else could get a hold of it?