{"meta":{"title":"Using pre-written building blocks in your workflow","intro":"You can use and customize pre-written actions to power your workflow.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/how-tos","title":"How-tos"},{"href":"/en/actions/how-tos/write-workflows","title":"Write workflows"},{"href":"/en/actions/how-tos/write-workflows/choose-what-workflows-do","title":"Choose what workflows do"},{"href":"/en/actions/how-tos/write-workflows/choose-what-workflows-do/find-and-customize-actions","title":"Find and customize actions"}],"documentType":"article"},"body":"# Using pre-written building blocks in your workflow\n\nYou can use and customize pre-written actions to power your workflow.\n\n## Browsing Marketplace actions in the workflow editor\n\nYou can search and browse actions directly in your repository's workflow editor. From the sidebar, you can search for a specific action, view featured actions, and browse featured categories. You can also view the number of stars an action has received from the GitHub community.\n\n1. In your repository, browse to the workflow file you want to edit.\n2. In the upper right corner of the file view, to open the workflow editor, click .\n \n3. To the right of the editor, use the GitHub Marketplace sidebar to browse actions. Actions with the badge indicate GitHub has verified the creator of the action as a partner organization.\n \n\n## Adding an action to your workflow\n\nYou can add an action to your workflow by referencing the action in your workflow file. The actions you use in your workflow can be defined in:\n\n* The same repository as your workflow file\n* Any public repository\n* A published Docker container image on Docker Hub\n\nYou can view the actions referenced in your GitHub Actions workflows as dependencies in the dependency graph of the repository containing your workflows. For more information, see “[Dependency graph](/en/code-security/concepts/supply-chain-security/dependency-graph).”\n\n> \\[!NOTE]\n> To enhance security, GitHub Actions does not support redirects for actions or reusable workflows. This means that when the owner, name of an action's repository, or name of an action is changed, any workflows using that action with the previous name will fail.\n\n### Adding an action from GitHub Marketplace\n\nAn action's listing page includes the action's version and the workflow syntax required to use the action. To keep your workflow stable even when updates are made to an action, you can reference the version of the action to use by specifying the Git or Docker tag number in your workflow file.\n\n1. Navigate to the action you want to use in your workflow.\n2. Click to view the full marketplace listing for the action.\n3. Under \"Installation\", click to copy the workflow syntax.\n \n4. Paste the syntax as a new step in your workflow. For more information, see [Workflow syntax for GitHub Actions](/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsteps).\n5. If the action requires you to provide inputs, set them in your workflow. For information on inputs an action might require, see [Using pre-written building blocks in your workflow](/en/actions/how-tos/write-workflows/choose-what-workflows-do/find-and-customize-actions#using-inputs-and-outputs-with-an-action).\n\nYou can also enable Dependabot version updates for the actions that you add to your workflow. For more information, see [Keeping your actions up to date with Dependabot](/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/auto-update-actions).\n\n### Adding an action from the same repository\n\nIf an action is defined in the same repository where your workflow file uses the action, you can reference the action with the `$/path/to/dir` self repository reference, or with the `{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. The `$/` syntax is not available in GitHub Enterprise Server.\n\nExample repository file structure:\n\n```shell\n|-- hello-world (repository)\n| |__ .github\n| └── workflows\n| └── my-first-workflow.yml\n| └── actions\n| |__ hello-world-action\n| └── action.yml\n```\n\nWe recommend referencing the action with the `$/path/to/dir` self repository reference. This resolves to the same repository at the running commit, so you do not need to check out the repository first. For more information about how `$/` compares to `{owner}/{repo}@{ref}` and `./`, see [Workflow syntax for GitHub Actions](/en/actions/reference/workflows-and-actions/workflow-syntax#example-using-an-action-in-the-same-repository-as-the-workflow-at-the-running-commit-recommended).\n\nExample workflow file using `$/`:\n\n```yaml\njobs:\n my_first_job:\n runs-on: ubuntu-latest\n steps:\n # This step references an action in the same repository at the\n # running commit. No repository checkout is required.\n - name: Use hello-world-action\n uses: $/.github/actions/hello-world-action\n```\n\nYou can also reference the action with the relative `./path/to/dir` syntax, but it is more error-prone. The path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`), so it requires a checkout step, and if the action checks out the repository to a location different than the workflow, the relative path must be updated.\n\nExample workflow file using `./`:\n\n```yaml\njobs:\n my_first_job:\n runs-on: ubuntu-latest\n steps:\n # This step checks out a copy of your repository.\n - name: My first step - check out repository\n uses: actions/checkout@v6\n # This step references the directory that contains the action.\n - name: Use local hello-world-action\n uses: ./.github/actions/hello-world-action\n```\n\nThe `action.yml` file is used to provide metadata for the action. Learn about the content of this file in [Metadata syntax reference](/en/actions/reference/workflows-and-actions/metadata-syntax).\n\n### Adding an action from a different repository\n\nIf an action is defined in a different repository than your workflow file, you can reference the action with the `{owner}/{repo}@{ref}` syntax in your workflow file.\n\nThe action must be stored in a public repository.\n\n```yaml\njobs:\n my_first_job:\n steps:\n - name: My first step\n uses: actions/setup-node@v7\n```\n\n### Referencing a container on Docker Hub\n\nIf an action is defined in a published Docker container image on Docker Hub, you must reference the action with the `docker://{image}:{tag}` syntax in your workflow file. To protect your code and data, we strongly recommend you verify the integrity of the Docker container image from Docker Hub before using it in your workflow.\n\n```yaml\njobs:\n my_first_job:\n steps:\n - name: My first step\n uses: docker://alpine:3.8\n```\n\nFor some examples of Docker actions, see the [Docker-image.yml workflow](https://github.com/actions/starter-workflows/blob/main/ci/docker-image.yml) and [Creating a Docker container action](/en/actions/tutorials/use-containerized-services/create-a-docker-container-action).\n\n### Security hardening for using actions in your workflows\n\nGitHub provides security features that you can use to increase the security of your workflows. You can use GitHub's built-in features to ensure you are notified about vulnerabilities in the actions you consume, or to automate the process of keeping the actions in your workflows up to date. For more information, see [Secure use reference](/en/actions/reference/security/secure-use).\n\n## Using release management for your custom actions\n\nThe creators of a community action have the option to use tags, branches, or SHA values to manage releases of the action. Similar to any dependency, you should indicate the version of the action you'd like to use based on your comfort with automatically accepting updates to the action.\n\nYou will designate the version of the action in your workflow file. Check the action's documentation for information on their approach to release management, and to see which tag, branch, or SHA value to use.\n\n> \\[!NOTE]\n> We recommend that you use a SHA value when using third-party actions. However, it's important to note Dependabot will only create Dependabot alerts for vulnerable GitHub Actions that use semantic versioning. For more information, see [Secure use reference](/en/actions/reference/security/secure-use#using-third-party-actions) and [Dependabot alerts](/en/code-security/concepts/supply-chain-security/dependabot-alerts).\n\n### Using tags\n\nTags are useful for letting you decide when to switch between major and minor versions, but these are more ephemeral and can be moved or deleted by the maintainer. This example demonstrates how to target an action that's been tagged as `v1.0.1`:\n\n```yaml\nsteps:\n - uses: actions/javascript-action@v1.0.1\n```\n\n### Using SHAs\n\nIf you need more reliable versioning, you should use the SHA value associated with the version of the action. SHAs are immutable and therefore more reliable than tags or branches. However, this approach means you will not automatically receive updates for an action, including important bug fixes and security updates. You must use a commit's full SHA value, and not an abbreviated value. When selecting a SHA, you should verify it is from the action's repository and not a repository fork. This example targets an action's SHA:\n\n```yaml\nsteps:\n - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f\n```\n\n### Using branches\n\nSpecifying a target branch for the action means it will always run the version currently on that branch. This approach can create problems if an update to the branch includes breaking changes. This example targets a branch named `@main`:\n\n```yaml\nsteps:\n - uses: actions/javascript-action@main\n```\n\nFor more information, see [Managing custom actions](/en/actions/how-tos/create-and-publish-actions/manage-custom-actions#using-release-management-for-actions).\n\n## Using inputs and outputs with an action\n\nAn action often accepts or requires inputs and generates outputs that you can use. For example, an action might require you to specify a path to a file, the name of a label, or other data it will use as part of the action processing.\n\nTo see the inputs and outputs of an action, check the `action.yml` in the root directory of the repository.\n\nIn this example `action.yml`, the `inputs` keyword defines a required input called `file-path`, and includes a default value that will be used if none is specified. The `outputs` keyword defines an output called `results-file`, which tells you where to locate the results.\n\n```yaml\nname: \"Example\"\ndescription: \"Receives file and generates output\"\ninputs:\n file-path: # id of input\n description: \"Path to test script\"\n required: true\n default: \"test-file.js\"\noutputs:\n results-file: # id of output\n description: \"Path to results file\"\n```"}