Creating a Docker container

Note: GitHub Actions are currently available as a limited public beta, which means you should avoid using it for high-value workflows and content during this beta period. Creating workflows that use GitHub Actions is limited to private repositories during the limited public beta.

Features and requirements may change at any time during this period. You can request to join the limited public beta on the GitHub Actions page. If you're participating in the beta, please contact support if you have any questions.

GitHub Actions execute in Docker containers. An action can use an existing publicly available Docker image, or you can create your own Docker image by including a Dockerfile with your code. To learn more about Docker, see the Docker documentation.

A Dockerfile has a file format that contains instructions and arguments, which define the contents and startup behavior of the Docker container. See "Dockerfile reference" for a list of instructions that Docker supports.

The following sections describe how the instructions in a Dockerfile work with the actions declared in the main.workflow file and the visual workflow editor. See "Creating a workflow with GitHub Actions" in the GitHub Help documentation to learn more about the visual workflow editor.

Note: Docker container logs are limited to a maximum size 64 KB.

USER

GitHub actions must be run by the default Docker user (root). Do not use the USER instruction in your Dockerfile, otherwise you won't be able to access the GITHUB_WORKSPACE.

FROM

The first instruction in the Dockerfile must be FROM, which selects a base image. These are some best practices when setting the FROM argument:

  • It's recommended to use official Docker images. For example, python: or ruby:.
  • Use a version tag, preferably with a major version, when it exists. For example, node:10.
  • When specifying a Docker image version, don't use latest. For example, don't use node:latest.
  • It's recommended to use Docker images based on the Debian operating system.

WORKDIR

GitHub sets the working directory to /github/workspace. You can read the working directory path set by GitHub from the GITHUB_WORKSPACE environment variable. It's recommended to not use the WORKDIR instruction in your Dockerfile. Before the action executes, GitHub will mount /github on top of anything that was at that location in the Docker image and set /github/workspace as the working directory. See Docker's WORKDIR reference documentation for more information.

ENTRYPOINT

If an action does not use the runs configuration option, the commands in ENTRYPOINT will execute.

Many containers use the exec form of the ENTRYPOINT instruction, which means that the args in main.workflow files won't run in a command shell. For example, if the action's args contain an environment variable, the variable will not be substituted. To supply args to a Docker container that uses the exec form in the ENTRYPOINT, we recommend creating a shell script called entrypoint.sh. Explicitly use the system's POSIX-compliant shell, by adding the #!/bin/sh shebang at the top of the entrypoint.sh file. The shell script can read the commands from a string:

#!/bin/sh

sh -c "docker $*"

The $* parameter expands the args supplied in an array individually and splits args in a string separated by whitespace.

For example, both of these actions are functionally equivalent:

args passed in string format

action "Tag Docker Image" {
  needs = ["build"]
  uses = "actions/docker/cli@master"
  args = "tag hello octocat/hello:$GITHUB_SHA"
}

args passed in array format

action "Tag Docker Image" {
  needs = ["build"]
  uses = "actions/docker/cli@master"
  args = ["tag", "hello", "octocat/hello:$GITHUB_SHA"]
}

CMD

If the main.workflow file defines args for an action, the args will be used in place of the CMD instruction.

If you use CMD in your Dockerfile, use these guidelines ordered by preference:

  1. Document required arguments and omit them from the CMD instruction.
  2. Use defaults that allow using the action without specifying any args.
  3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.

LABEL

You can use the LABEL instruction to show your action in the visual workflow editor.

LABEL key Description
com.github.actions.name The name of the action.
com.github.actions.description A short description of the action.
com.github.actions.icon The name of the Feather icon to use. See "Supported feature icons" for the list of supported icons.
com.github.actions.color The background color used in the visual workflow editor for the action. Can be one of: white, yellow, blue, green, orange, red, purple, or gray-dark.

It's recommended to also include these labels that describe the action:

LABEL key Description
repository The URL of the action's repository.
homepage The URL of the action's home web page.
maintainer The name of the person who maintains the action. You can optionally include an email address. For example, LABEL "maintainer"="Mona the octocat <octocat@github.com>".

Supported feather icons

These are the Feather icons supported by the LABEL instruction.

  • activity
  • airplay
  • alert-circle
  • alert-octagon
  • alert-triangle
  • align-center
  • align-justify
  • align-left
  • align-right
  • anchor
  • aperture
  • archive
  • arrow-down-circle
  • arrow-down-left
  • arrow-down-right
  • arrow-down
  • arrow-left-circle
  • arrow-left
  • arrow-right-circle
  • arrow-right
  • arrow-up-circle
  • arrow-up-left
  • arrow-up-right
  • arrow-up
  • at-sign
  • award
  • bar-chart-2
  • bar-chart
  • battery-charging
  • battery
  • bell-off
  • bell
  • bluetooth
  • bold
  • book-open
  • book
  • bookmark
  • box
  • briefcase
  • calendar
  • camera-off
  • camera
  • cast
  • check-circle
  • check-square
  • check
  • chevron-down
  • chevron-left
  • chevron-right
  • chevron-up
  • chevrons-down
  • chevrons-left
  • chevrons-right
  • chevrons-up
  • circle
  • clipboard
  • clock
  • cloud-drizzle
  • cloud-lightning
  • cloud-off
  • cloud-rain
  • cloud-snow
  • cloud
  • code
  • command
  • compass
  • copy
  • corner-down-left
  • corner-down-right
  • corner-left-down
  • corner-left-up
  • corner-right-down
  • corner-right-up
  • corner-up-left
  • corner-up-right
  • cpu
  • credit-card
  • crop
  • crosshair
  • database
  • delete
  • disc
  • dollar-sign
  • download-cloud
  • download
  • droplet
  • edit-2
  • edit-3
  • edit
  • external-link
  • eye-off
  • eye
  • facebook
  • fast-forward
  • feather
  • file-minus
  • file-plus
  • file-text
  • file
  • film
  • filter
  • flag
  • folder-minus
  • folder-plus
  • folder
  • gift
  • git-branch
  • git-commit
  • git-merge
  • git-pull-request
  • globe
  • grid
  • hard-drive
  • hash
  • headphones
  • heart
  • help-circle
  • home
  • image
  • inbox
  • info
  • italic
  • layers
  • layout
  • life-buoy
  • link-2
  • link
  • list
  • loader
  • lock
  • log-in
  • log-out
  • mail
  • map-pin
  • map
  • maximize-2
  • maximize
  • menu
  • message-circle
  • message-square
  • mic-off
  • mic
  • minimize-2
  • minimize
  • minus-circle
  • minus-square
  • minus
  • monitor
  • moon
  • more-horizontal
  • more-vertical
  • move
  • music
  • navigation-2
  • navigation
  • octagon
  • package
  • paperclip
  • pause-circle
  • pause
  • percent
  • phone-call
  • phone-forwarded
  • phone-incoming
  • phone-missed
  • phone-off
  • phone-outgoing
  • phone
  • pie-chart
  • play-circle
  • play
  • plus-circle
  • plus-square
  • plus
  • pocket
  • power
  • printer
  • radio
  • refresh-ccw
  • refresh-cw
  • repeat
  • rewind
  • rotate-ccw
  • rotate-cw
  • rss
  • save
  • scissors
  • search
  • send
  • server
  • settings
  • share-2
  • share
  • shield-off
  • shield
  • shopping-bag
  • shopping-cart
  • shuffle
  • sidebar
  • skip-back
  • skip-forward
  • slash
  • sliders
  • smartphone
  • speaker
  • square
  • star
  • stop-circle
  • sun
  • sunrise
  • sunset
  • tablet
  • tag
  • target
  • terminal
  • thermometer
  • thumbs-down
  • thumbs-up
  • toggle-left
  • toggle-right
  • trash-2
  • trash
  • trending-down
  • trending-up
  • triangle
  • truck
  • tv
  • type
  • umbrella
  • underline
  • unlock
  • upload-cloud
  • upload
  • user-check
  • user-minus
  • user-plus
  • user-x
  • user
  • users
  • video-off
  • video
  • voicemail
  • volume-1
  • volume-2
  • volume-x
  • volume
  • watch
  • wifi-off
  • wifi
  • wind
  • x-circle
  • x-square
  • x
  • zap-off
  • zap
  • zoom-in
  • zoom-out