Creating a composite run steps action

In this guide, you'll learn how to build a composite run steps action.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server, and GitHub One. GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. For more information, see "GitHub's products."

In this article

Did this doc help you?


In this guide, you'll learn about the basic components needed to create and use a packaged composite run steps action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" and then "Goodbye", or if you provide a custom name, it prints "Hello [who-to-greet]" and then "Goodbye". The action also maps a random number to the random-number output variable, and runs a script named

Once you complete this project, you should understand how to build your own composite run steps action and test it in a workflow.


Before you begin, you'll create a GitHub repository.

  1. Create a new public repository on GitHub. You can choose any repository name, or use the following hello-world-composite-run-steps-action example. You can add these files after your project has been pushed to GitHub. For more information, see "Create a new repository."

  2. Clone your repository to your computer. For more information, see "Cloning a repository."

  3. From your terminal, change directories into your new repository.

    cd hello-world-composite-run-steps-action
  4. In the hello-world-composite-run-steps-action repository, create a new file called, and add the following example code:

    echo "Goodbye"
  5. From your terminal, make executable and check it into your repository.

    chmod +x
  6. From your terminal, check in your file.

    git add
    git commit -m "Add goodbye script"
    git push

Creating an action metadata file

  1. In the hello-world-composite-run-steps-action repository, create a new file called action.yml and add the following example code. For more information about this syntax, see "runs for a composite run steps".


    name: 'Hello World'
    description: 'Greet someone'
      who-to-greet:  # id of input
        description: 'Who to greet'
        required: true
        default: 'World'
        description: "Random number"
        value: ${{ steps.random-number-generator.outputs.random-id }}
      using: "composite"
        - run: echo Hello ${{ inputs.who-to-greet }}.
          shell: bash
        - id: random-number-generator
          run: echo "::set-output name=random-id::$(echo $RANDOM)"
          shell: bash
        - run: ${{ github.action_path }}/
          shell: bash

    This file defines the who-to-greet input, maps the random generated number to the random-number output variable, and runs the script. It also tells the runner how to execute the composite run steps action.

    For more information about managing outputs, see "outputs for a composite run steps".

    For more information about how to use github.action_path, see "github context".

  2. Create a new label. This example uses a label called v1 for the main branch. For more information, see "Creating a label ."

Testing out your action in a workflow

The following workflow code uses the completed hello world action that you made in "Creating an action metadata file".

Copy the workflow code into a .github/workflows/main.yml file in another repository, but replace actions/hello-world-composite-run-steps-action@v1 with the repository and label you created. You can also replace the who-to-greet input with your name.


on: [push]

    runs-on: ubuntu-latest
    name: A job to say hello
    - uses: actions/checkout@v2
    - id: foo
      uses: actions/hello-world-composite-run-steps-action@v1
        who-to-greet: 'Mona the Octocat'
    - run: echo random-number ${{ }} 
      shell: bash

From your repository, click the Actions tab, and select the latest workflow run. The output should include: "Hello Mona the Octocat", the result of the "Goodbye" script, and a random number.

Did this doc help you?