Deprecated

This repository is being replaced with docker/build-push-action@v2 which includes significant changes and now uses Docker Buildx. It will not receive any future updates, please update your workflows.

Upgrade notes with many usage examples have been added to handle most use cases.

About

The core code base for Docker's GitHub Actions (https://github.com/features/actions). This code is used to build the docker/github-actions image that provides the functionality used by the published Docker GitHub Action:

• Build and push Docker images action

github-actions runs a command line tool that shells out to docker to perform the various functions. Parameters are supplied to github-actions using environment variables in the form described by the GitHub Actions documentation. github-actions uses some of the default GitHub Actions environment variables as described in the individual commands section.

Commands

Commands can be called using docker run docker/github-actions {command}

login

Does a docker login using the supplied username and password. Will default to Docker Hub but can be supplied a server address to login to a third-party registry as required.

inputs

Environment Variable	Required	Description
INPUT_USERNAME	yes	Username to login with
INPUT_PASSWORD	yes	Password to login with
INPUT_REGISTRY	no	Registry server to login to. Defaults to Docker Hub

build

Builds and tags a docker image.

inputs

Environment Variable	Required	Description
INPUT_PATH	yes	Path to build from
INPUT_DOCKERFILE	no	Path to Dockerfile
INPUT_ADD_GIT_LABELS	no	Adds git labels (see below)
INPUT_TARGET	no	Target build stage to build
INPUT_BUILD_ARGS	no	Comma-delimited list of build-args
INPUT_LABELS	no	Comma-delimited list of labels
INPUT_CACHE_FROMS	no	Comma-delimited list of cache-froms

See the tagging section for information on tag inputs

Git labels

When INPUT_ADD_GIT_LABELS is true labels are automatically added to the image that contain data about the current state of the git repo based on the standards set out in https://github.com/opencontainers/image-spec/blob/master/annotations.md.

3 labels are supported:

Label	Description
org.opencontainers.image.created	Date and time on which the image was built (string, date-time as defined by RFC 3339).
org.opencontainers.image.source	URL to this repository. E.g. https://github.com/myorg/myrepository
org.opencontainers.image.revision	The full git sha of this commit.

push

Pushes a docker image.

inputs

See the tagging section for information on tag inputs

build-push

Builds, logs in, and pushes a docker image.

inputs

Same as the login and build commands with the addition of

Environment Variable	Required	Description
INPUT_PUSH	no	Will push the image if true

Tagging

Tagging of images can be set manually, left to github-actions to automate, or a combination of the both.

There are 4 input variables used for tagging

Environment Variable	Required	Description
INPUT_REGISTRY	no	Registry server to tag with
INPUT_REPOSITORY	yes	Repository to tag with
INPUT_TAGS	no	Hard coded comma-delimited list of tags
INPUT_TAG_WITH_REF	no	If true then github-actions will add tags depending on the git ref automatically as described below
INPUT_TAG_WITH_SHA	no	If true then github-actions will add a tag in the form sha-{git-short-sha}

If INPUT_REGISTRY is set then all tags are prefixed with {INPUT_REGISTRY}/{INPUT_REPOSITORY}:. If not then all tags are prefixed with {INPUT_REPOSITORY}:

Auto tags depend on the git reference that the run is associated with. The reference is passed to github-actions using the GitHub actions GITHUB_REF enviroment variable.

If the reference is refs/heads/{branch-name} then the tag {branch-name} is added. For the master branch the {branch-name} is replaced with latest.

If the reference is refs/pull/{pr} then the tag pr-{pr} is added.

If the reference is refs/tags/{tag-name} then the tag {tag-name} is added.

Any / in the auto tags are replaced with -.

For example if the environment variables are as follows:

Variable	Value
INPUT_REGISTRY
INPUT_REPOSITORY	myorg/myimage
INPUT_TAGS	foo,bar
INPUT_TAG_WITH_REF	true
GITHUB_REF	refs/tags/v0.1

Then the image will be tagged with:

myorg/myimage:foo
myorg/myimage:bar
myorg/myimage:v0.1

If the variables are as follows:

Variable	Value
INPUT_REGISTRY	myregistry
INPUT_REPOSITORY	myorg/myimage
INPUT_TAGS	foo,bar
INPUT_TAG_WITH_REF	true
INPUT_TAG_WITH_SHA	true
GITHUB_REF	refs/heads/master
GITHUB_SHA	c6df8c68eb71799f9c9ab4a4a4650d6aabd7e415

Then the image will be tagged with:

myregistry/myorg/myimage:foo
myregistry/myorg/myimage:bar
myregistry/myorg/myimage:lastest
myregistry/myorg/myimage:sha-c6df8c6

Building github-actions

The code is written in Go v1.13 with go mod. It can be built locally using the Makefile or in docker using the docker.Makefile.

make -f docker.Makefile will build the code, check the linting using golangci-lint, run the go tests, and build the image with a tag of docker/github-actions:latest

make -f docker.Makefile image will build the github-actions image without a tag and without running test or lint checking

make -f docker.Makefile cli will build the cli and copy it to ./bin/github-actions

make -f docker.Makefile test will run the unit and e2e tests