GitHub Actions enable you to create custom software development life cycle (SDLC) workflows directly in your GitHub repository.
GitHub Actions is currently in limited public beta and is subject to change. We strongly recommend that you do not use this feature for high-value workflows and content during the beta period. For more information about the beta, see "About GitHub Actions."
For more information about using GitHub Actions, see "Automating your workflow with GitHub Actions."
In this article
- About actions
- Types of GitHub Actions
- Choosing a location for your action
- Versioning your action
- Creating a README file for your action
- Further reading
You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with GitHub's APIs and any publicly available third-party API. For example, an action can publish npm modules, send SMS alerts when urgent issues are created, or deploy production-ready code.
You can write your own actions to use in your workflow or share the actions you build with the GitHub community. To share actions you've built, your repository must be public.
Actions run in a virtual environment or Docker container. You can define an action's inputs, outputs, and environment variables.
Types of actions
Docker container actions
Docker containers package the environment with the GitHub Actions code. This creates a more consistent and reliable unit of work because the consumer of the action does not need to worry about the tools or dependencies. Docker container actions can only execute in the GitHub-hosted Linux environment.
You must include a GitHub Actions configuration file to provide metadata about the action.
Choosing a location for your action
If you're developing an action for other people to use, we recommend 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.
If you're building an action that you don't plan to make available to the public, you can store the action's files in any location in your repository. If you plan to combine action, workflow, and application code in a single repository, we recommend storing actions in the
.github directory. For example,
Versioning your action
Workflows can reference specific versions of actions using a commit SHA, branch, or tag.
steps: - uses: actions/setup-node@74bc508 # Reference a specific commit - uses: firstname.lastname@example.org # Reference the major version of a release - uses: actions/setup-node@master # Reference a branch
GitHub recommends using semantic versioning when creating actions to provide people with a stable experience. For more information, see "Semantic versioning."
- Create a release using semantic versioning (v1.0.9). For more information, see "Creating releases."
- Move the major version tag (v1, v2, etc.) to point to the Git ref of the current release. For more information, see "Git basics - tagging."
- Introduce a new major version tag (v2) for breaking changes that will break existing workflows. For example, changing an action's inputs would be a breaking change.
Creating a README file for your action
If you plan to publicly share your action, we recommend creating a README file to help people learn how to use your action. You can include this information in your
- A detailed description of what the action does
- Required input and output arguments
- Optional input and output arguments
- Secrets the action uses
- Environment variables the action uses
- An example of how to use your action in a workflow