Managing custom actions

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 others, 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, .github/actions/action-a and .github/actions/action-b.

Ensuring compatibility with other platforms

Many people access GitHub at a domain other than GitHub.com, such as GHE.com or a custom domain for GitHub Enterprise Server.

To ensure that your action is compatible with other platforms, do not use any hard-coded references to API URLs such as https://api.github.com. Instead, you can:

• Use environment variables (see Variables reference):

  • For the REST API, use the GITHUB_API_URL environment variable.
  • For GraphQL, use the GITHUB_GRAPHQL_URL environment variable.

• Use a toolkit such as @actions/github, which can automatically set the correct URLs.

Using release management for actions

If you're developing an action for other people to use, we recommend using release management to control how you distribute updates. Users can expect an action's patch version to include necessary critical fixes and security patches, while still remaining compatible with their existing workflows. You should consider releasing a new major version whenever your changes affect compatibility.

Under this release management approach, users should not be referencing an action's default branch, as it's likely to contain the latest code and consequently might be unstable. Instead, you can recommend that your users specify a major version when using your action, and only direct them to a more specific version if they encounter issues.

To use a specific action version, users can configure their GitHub Actions workflow to target a tag, a commit's SHA, or a branch named for a release.

Using tags for release management

We recommend using tags for actions release management. Using this approach, your users can easily distinguish between major and minor versions:

1. Develop and validate a release on a release branch (for example, release/v1).
2. Create a release with a release tag using semantic versioning (for example, v1.0.1). For more information, see Managing releases in a repository.
3. Move the major version tag (for example, v1) to point to the Git ref of the current release. For more information, see Git basics - tagging.
4. Introduce a new major version tag (for example, v2) for changes that will break existing workflows, such as changing an action's inputs.

Syntax for referencing tags

This example demonstrates how a user can reference a major version tag:

steps:
    - uses: actions/javascript-action@v1

This example demonstrates how a user can reference a specific patch release tag:

steps:
    - uses: actions/javascript-action@v1.0.1

Using branches for release management

If you prefer to use branch names for release management, this example demonstrates how to reference a named branch:

steps:
    - uses: actions/javascript-action@v1-beta

Using a commit's SHA for release management

Each Git commit receives a calculated SHA value, which is unique and immutable. Your action's users might prefer to rely on a commit's SHA value, as this approach can be more reliable than specifying a tag, which could be deleted or moved. However, this means that users will not receive further updates made to the action. You must use a commit's full SHA value, and not an abbreviated value.

steps:
    - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Creating a README file for your action

We recommend creating a README file to help people learn how to use your action. You can include this information in your README.md:

• 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