{"meta":{"title":"Creating a composite action","intro":"In this tutorial, you'll learn how to build a composite action.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/tutorials","title":"Tutorials"},{"href":"/en/actions/tutorials/create-actions","title":"Create actions"},{"href":"/en/actions/tutorials/create-actions/create-a-composite-action","title":"Create a composite action"}],"documentType":"article"},"body":"# Creating a composite action\n\nIn this tutorial, you'll learn how to build a composite action.\n\n## Introduction\n\nIn this guide, you'll learn about the basic components needed to create and use a packaged composite 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 `goodbye.sh`.\n\nOnce you complete this project, you should understand how to build your own composite action and test it in a workflow.\n\n> \\[!WARNING]\n> When creating workflows and actions, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see [Secure use reference](/en/actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections).\n\n### Composite actions and reusable workflows\n\nComposite actions allow you to collect a series of workflow job steps into a single action which you can then run as a single job step in multiple workflows. Reusable workflows provide another way of avoiding duplication, by allowing you to run a complete workflow from within other workflows. For more information, see [Reusing workflow configurations](/en/actions/using-workflows/avoiding-duplication).\n\n## Prerequisites\n\n> \\[!NOTE]\n> This example explains how to create a composite action within a separate repository. However, it is possible to create a composite action within the same repository. For more information, see [Creating a composite action](/en/actions/creating-actions/creating-a-composite-action#creating-a-composite-action-within-the-same-repository).\n\nBefore you begin, you'll create a repository on GitHub.\n\n1. Create a new public repository on GitHub. You can choose any repository name, or use the following `hello-world-composite-action` example. You can add these files after your project has been pushed to GitHub. For more information, see [Creating a new repository](/en/repositories/creating-and-managing-repositories/creating-a-new-repository).\n\n2. Clone your repository to your computer. For more information, see [Cloning a repository](/en/repositories/creating-and-managing-repositories/cloning-a-repository).\n\n3. From your terminal, change directories into your new repository.\n\n   ```shell copy\n   cd hello-world-composite-action\n   ```\n\n4. In the `hello-world-composite-action` repository, create a new file called `goodbye.sh` with example code:\n\n   ```shell copy\n   echo \"echo Goodbye\" > goodbye.sh\n   ```\n\n5. From your terminal, make `goodbye.sh` executable.\n\n   <div class=\"ghd-tool linux\">\n\n   ```shell copy\n   chmod +x goodbye.sh\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool mac\">\n\n   ```shell copy\n   chmod +x goodbye.sh\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool windows\">\n\n   ```shell copy\n   git add --chmod=+x -- goodbye.sh\n   ```\n\n   </div>\n\n6. From your terminal, check in your `goodbye.sh` file.\n\n   <div class=\"ghd-tool linux\">\n\n   ```shell copy\n   git add goodbye.sh\n   git commit -m \"Add goodbye script\"\n   git push\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool mac\">\n\n   ```shell copy\n   git add goodbye.sh\n   git commit -m \"Add goodbye script\"\n   git push\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool windows\">\n\n   ```shell copy\n   git commit -m \"Add goodbye script\"\n   git push\n   ```\n\n   </div>\n\n## Creating an action metadata file\n\n1. In the `hello-world-composite-action` repository, create a new file called `action.yml` and add the following example code. For more information about this syntax, see [Metadata syntax reference](/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions).\n\n   ```yaml copy\n   name: 'Hello World'\n   description: 'Greet someone'\n   inputs:\n     who-to-greet:  # id of input\n       description: 'Who to greet'\n       required: true\n       default: 'World'\n   outputs:\n     random-number:\n       description: \"Random number\"\n       value: ${{ steps.random-number-generator.outputs.random-number }}\n   runs:\n     using: \"composite\"\n     steps:\n       - name: Set Greeting\n         run: echo \"Hello $INPUT_WHO_TO_GREET.\"\n         shell: bash\n         env:\n           INPUT_WHO_TO_GREET: ${{ inputs.who-to-greet }}\n\n       - name: Random Number Generator\n         id: random-number-generator\n         run: echo \"random-number=$(echo $RANDOM)\" >> $GITHUB_OUTPUT\n         shell: bash\n\n       - name: Set GitHub Path\n         run: echo \"$GITHUB_ACTION_PATH\" >> $GITHUB_PATH\n         shell: bash\n         env:\n           GITHUB_ACTION_PATH: ${{ github.action_path }}\n\n       - name: Run goodbye.sh\n         run: goodbye.sh\n         shell: bash\n\n   ```\n\n   This file defines the `who-to-greet` input, maps the random generated number to the `random-number` output variable, adds the action's path to the runner system path (to locate the `goodbye.sh` script during execution), and runs the `goodbye.sh` script.\n\n   For more information about managing outputs, see [Metadata syntax reference](/en/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions).\n\n   For more information about how to use `github.action_path`, see [Contexts reference](/en/actions/learn-github-actions/contexts#github-context).\n\n2. From your terminal, check in your `action.yml` file.\n\n   ```shell copy\n   git add action.yml\n   git commit -m \"Add action\"\n   git push\n   ```\n\n3. From your terminal, add a tag. This example uses a tag called `v1`. For more information, see [About custom actions](/en/actions/creating-actions/about-custom-actions#using-release-management-for-actions).\n\n   ```shell copy\n   git tag -a -m \"Description of this release\" v1\n   git push --follow-tags\n   ```\n\n## Testing out your action in a workflow\n\nThe following workflow code uses the completed hello world action that you made in [Creating a composite action](/en/actions/creating-actions/creating-a-composite-action#creating-an-action-metadata-file).\n\nCopy the workflow code into a `.github/workflows/main.yml` file in another repository, replacing `OWNER` and `SHA` with the repository owner and the SHA of the commit you want to use, respectively. You can also replace the `who-to-greet` input with your name.\n\n```yaml copy\non: [push]\n\njobs:\n  hello_world_job:\n    runs-on: ubuntu-latest\n    name: A job to say hello\n    steps:\n      - uses: actions/checkout@v6\n      - id: foo\n        uses: OWNER/hello-world-composite-action@SHA\n        with:\n          who-to-greet: 'Mona the Octocat'\n      - run: echo random-number \"$RANDOM_NUMBER\"\n        shell: bash\n        env:\n          RANDOM_NUMBER: ${{ steps.foo.outputs.random-number }}\n```\n\nFrom 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.\n\n## Creating a composite action within the same repository\n\n1. Create a new subfolder called `hello-world-composite-action`, this can be placed in any subfolder within the repository. However, it is recommended that this be placed in the `.github/actions` subfolder to make organization easier.\n\n2. In the `hello-world-composite-action` folder, do the same steps to create the `goodbye.sh` script\n\n   ```shell copy\n   echo \"echo Goodbye\" > goodbye.sh\n   ```\n\n   <div class=\"ghd-tool linux\">\n\n   ```shell copy\n   chmod +x goodbye.sh\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool mac\">\n\n   ```shell copy\n   chmod +x goodbye.sh\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool windows\">\n\n   ```shell copy\n   git add --chmod=+x -- goodbye.sh\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool linux\">\n\n   ```shell copy\n   git add goodbye.sh\n   git commit -m \"Add goodbye script\"\n   git push\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool mac\">\n\n   ```shell copy\n   git add goodbye.sh\n   git commit -m \"Add goodbye script\"\n   git push\n   ```\n\n   </div>\n\n   <div class=\"ghd-tool windows\">\n\n   ```shell copy\n   git commit -m \"Add goodbye script\"\n   git push\n   ```\n\n   </div>\n\n3. In the `hello-world-composite-action` folder, create the `action.yml` file based on the steps in [Creating a composite action](/en/actions/creating-actions/creating-a-composite-action#creating-an-action-metadata-file).\n\n4. When using the action, use the relative path to the folder where the composite action's `action.yml` file is located in the `uses` key. The below example assumes it is in the `.github/actions/hello-world-composite-action` folder.\n\n```yaml copy\non: [push]\n\njobs:\n  hello_world_job:\n    runs-on: ubuntu-latest\n    name: A job to say hello\n    steps:\n      - uses: actions/checkout@v6\n      - id: foo\n        uses: ./.github/actions/hello-world-composite-action\n        with:\n          who-to-greet: 'Mona the Octocat'\n      - run: echo random-number \"$RANDOM_NUMBER\"\n        shell: bash\n        env:\n          RANDOM_NUMBER: ${{ steps.foo.outputs.random-number }}\n```"}