Creating a new GitHub Action

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.

You can create actions in a repository you own by adding a Dockerfile. To share GitHub Actions with the GitHub community, your repository must be public.

All actions require a Dockerfile. An action may also include an entrypoint.sh file, to execute arguments, and any other files that contain the action's code. For example, an action called action-a might have this directory structure:

|-- hello-world (repository)
|   |__ .github
|       |__ main.workflow
|   |__ action-a
|       │__  Dockerfile
|       │__  README.md
|       |__  entrypoint.sh  
|

During the limited public beta, you can only create workflows that use actions in private repositories. To use an action in your repository, refer to the action in your .workflow using a path relative to the repository directory. For example, if your repository had the directory structure above, you would use this relative path to use action-a in a workflow for the hello-world repository:

action "action a" {
  uses = "./action-a/"
}

Every action should have a README.md file in the action's subdirectory that includes this information:

  • A detailed description of what the action does.
  • Environment variables the action uses.
  • Secrets the action uses. Production secrets should not be stored in the API during the limited public beta period.
  • Required arguments.
  • Optional arguments.

See "Creating a Docker container" to learn more about creating a custom Docker container and how you can use entrypoint.sh.

Choosing a location for your action

If you are developing an action for other people to use, GitHub recommends keeping the action in its own repository instead of bundling it with other application code. This allows you to version, track, and release the action just like any other software. Storing an action in its own repository makes it easier for the GitHub community to discover the action, narrows the scope of the code base for developers fixing issues and extending the action, and decouples the action's versioning from the versioning of other application code.

Using shell scripts to create actions

Shell scripts are a great way to write the code in GitHub Actions. If you can write an action in under 100 lines of code and it doesn't require complex or multi-line command arguments, a shell script is a great tool for the job. When writing actions using a shell script, following these guidelines:

  • Use a POSIX-standard shell when possible. Use the #!/bin/sh shebang to use the system's default shell. By default, Ubuntu and Debian use the dash shell, and Alpine uses the ash shell. Using the default shell requires you to avoid using bash or shell-specific features in your script.
  • Use set -eu in your shell script to avoid continuing when errors or undefined variables are present.

Hello world action example

You can create a new action by adding a Dockerfile to the directory in your repository that contains your action code.

This example code creates a simple action that writes arguments to standard output (stdout). An action declared in a main.workflow would pass the arguments that this action writes to stdout. To learn about the instructions used in the Dockerfile, see "Creating a Docker container."

See "Creating a new workflow" for an example workflow that uses this action. This example uses the "LABEL" instruction to add the action to the sidebar in the workflow visual editor.

The two files you need to create an action are shown below:

./action-a/Dockerfile

FROM debian:9.5-slim

LABEL "com.github.actions.name"="Hello World"
LABEL "com.github.actions.description"="Write arguments to the standard output"
LABEL "com.github.actions.icon"="mic"
LABEL "com.github.actions.color"="purple"

LABEL "repository"="http://github.com/octocat/hello-world"
LABEL "homepage"="http://github.com/actions"
LABEL "maintainer"="Octocat <octocat@github.com>"

ADD entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

./action-a/entrypoint.sh

#!/bin/sh -l

sh -c "echo $*"

Your code must be executable. Make sure the entrypoint.sh file has execute permissions before using it in a workflow. You can modify the permission from your terminal using this command:

chmod +x entrypoint.sh

This action echos the arguments you pass the action. For example, if you were to pass the arguments "Hello World", you'd see this output in the command shell:

Hello World

If you add these two files to your repository, you'll see this action available when creating a workflow in the visual editor. See "Creating a workflow with GitHub Actions" in the GitHub Help documentation to learn more about the visual workflow editor.

A GitHub Action available in the visual workflow editor