Creating a new GitHub Action

New release: GitHub Actions is now available in a new limited public beta. This version offers a new workflow configuration and built-in continuous integration and continuous deployment capabilities. We strongly recommend you avoid using it for high-value workflows and content during this public beta period. To request to join the limited public beta, see the GitHub Actions page. For more information, see "About GitHub Actions" in the GitHub Help documentation.

GitHub Support will only provide support for the YAML syntax and no longer provides support for the HCL syntax.

If you participated in the limited public beta and created workflows with the HCL syntax GitHub Actions, you will need to upgrade to the new limited public beta that uses YAML syntax. When your repository is eligible to upgrade, you'll see an invitation in your repository. You must accept the invitation before you can use the new limited public beta.

Once you've upgraded, any workflows that you created with the HCL syntax will need to be updated to the new YAML syntax. To automatically convert your workflows, see "Migrating GitHub Actions from HCL syntax to YAML syntax" in the GitHub Help documentation.

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 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
|       │__
|       |__  

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

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. Labels are also required to publish the action in the GitHub Marketplace.

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


FROM debian:9.5-slim

LABEL ""="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"=""
LABEL "homepage"=""
LABEL "maintainer"="Octocat <>"



#!/bin/sh -l

sh -c "echo $*"

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

chmod +x

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