github/branch-deploy
Enabling Branch Deployments through IssueOps with GitHub Actions
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit Jul 6, 2026
- License
- MIT
Pinned Snippet
uses: github/branch-deploy@de4d10ee17c3117a2076aff489ba03fadf225f35 # v11.1.5tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| github_token | The GitHub token used to create an authenticated client - Provided for you by default! | yes | ${{ github.token }} |
| status | The status of the GitHub Actions - For use in the post run workflow - Provided for you by default! | yes | ${{ job.status }} |
| environment | The name of the default environment to deploy to. Example: by default, if you type `.deploy`, it will assume "production" as the default environment | no | production |
| environment_targets | Optional (or additional) target environments to select for use with deployments. Example, "production,development,staging". Example usage: `.deploy to development`, `.deploy to production`, `.deploy to staging` | no | production,development,staging |
| draft_permitted_targets | Optional environments which can allow "draft" pull requests to be deployed. By default, this input option is empty and no environments allow deployments sourced from a pull request in a "draft" state. Examples: "development,staging" | no | "" |
| environment_urls | Optional target environment URLs to use with deployments. This input option is a mapping of environment names to URLs and the environment names must match the "environment_targets" input option. This option is a comma separated list with pipes (|) separating the environment from the URL. Note: "disabled" is a special keyword to disable an environment url if you enable this option. Format: "<environment1>|<url1>,<environment2>|<url2>,etc" Example: "production|https://myapp.com,development|https://dev.myapp.com,staging|disabled" | no | "" |
| environment_url_in_comment | If the environment_url detected in the deployment should be appended to the successful deployment comment or not. Examples: "true" or "false" | no | true |
| production_environments | A comma separated list of environments that should be treated as "production". GitHub defines "production" as an environment that end users or systems interact with. Example: "production,production-eu". By default, GitHub will set the "production_environment" to "true" if the environment name is "production". This option allows you to override that behavior so you can use "prod", "prd", "main", "production-eu", etc. as your production environment name. ref: https://github.com/github/branch-deploy/issues/208 | no | production |
| reaction | If set, the specified emoji "reaction" is put on the comment to indicate that the trigger was detected. For example, "rocket" or "eyes" | no | eyes |
| trigger | The string to look for in comments as an IssueOps trigger. Example: ".deploy" | no | .deploy |
| noop_trigger | The string to look for in comments as an IssueOps noop trigger. Example: ".noop" | no | .noop |
| lock_trigger | The string to look for in comments as an IssueOps lock trigger. Used for locking branch deployments on a specific branch. Example: ".lock" | no | .lock |
| unlock_trigger | The string to look for in comments as an IssueOps unlock trigger. Used for unlocking branch deployments. Example: ".unlock" | no | .unlock |
| help_trigger | The string to look for in comments as an IssueOps help trigger. Example: ".help" | no | .help |
| lock_info_alias | An alias or shortcut to get details about the current lock (if it exists) Example: ".info" | no | .wcid |
| permissions | The allowed GitHub permissions an actor can have to invoke IssueOps commands - Example: "write,admin" | yes | write,admin |
| commit_verification | Whether or not to enforce commit verification before a deployment can continue. Default is "false" | no | false |
| param_separator | The separator to use for parsing parameters in comments in deployment requests. Parameters will are saved as outputs and can be used in subsequent steps | no | | |
| global_lock_flag | The flag to pass into the lock command to lock all environments. Example: "--global" | no | --global |
| stable_branch | The name of a stable branch to deploy to (rollbacks). Example: "main" | no | main |
| update_branch | Determine how you want this Action to handle "out-of-date" branches. Available options: "disabled", "warn", "force". "disabled" means that the Action will not care if a branch is out-of-date. "warn" means that the Action will warn the user that a branch is out-of-date and exit without deploying. "force" means that the Action will force update the branch. Note: The "force" option is not recommended due to Actions not being able to re-run CI on commits originating from Actions itself | no | warn |
| outdated_mode | The mode to use for determining if a branch is up-to-date or not before allowing deployments. This option is closely related to the "update_branch" input option above. There are three available modes to choose from "pr_base", "default_branch", or "strict". The default is "strict" to help ensure that deployments are using the most up-to-date code. Please see the docs/outdated_mode.md document for more details. | no | strict |
| required_contexts | Manually enforce commit status checks before a deployment can continue. Only use this option if you wish to manually override the settings you have configured for your branch protection settings for your GitHub repository. Default is "false" - Example value: "context1,context2,context3" - In most cases you will not need to touch this option | no | false |
| skip_ci | A comma separated list of environments that will not use passing CI as a requirement for deployment. Use this option to explicitly bypass branch protection settings for a certain environment in your repository. Default is an empty string "" - Example: "development,staging" | no | "" |
| checks | This input defines how the branch-deploy Action will handle the status of CI checks on your PR/branch before deployments can continue. `"all"` requires that all CI checks must pass in order for a deployment to be triggered. `"required"` only waits for required CI checks to be passing. You can also pass in the names of your CI jobs in a comma separated list. View the documentation (docs/checks.md) for more details. | no | all |
| ignored_checks | A comma separated list of checks that will be ignored when determining if a deployment can continue. This setting allows you to skip failing, pending, or incomplete checks regardless of the `checks` setting above. Example: "lint,markdown-formatting,update-pr-label". View the documentation (docs/checks.md) for more details. | no | "" |
| skip_reviews | A comma separated list of environment that will not use reviews/approvals as a requirement for deployment. Use this options to explicitly bypass branch protection settings for a certain environment in your repository. Default is an empty string "" - Example: "development,staging" | no | "" |
| allow_forks | Allow branch deployments to run on repository forks. Default is "false". Set to "true" only when your workflow intentionally supports deployments from forked pull requests. | no | false |
| admins | A comma separated list of GitHub usernames or teams that should be considered admins by this Action. Admins can deploy pull requests without the need for branch protection approvals. Example: "monalisa,octocat,my-org/my-team" | no | false |
| admins_pat | A GitHub personal access token with "read:org" scopes. This is only needed if you are using the "admins" option with a GitHub org team. For example: "my-org/my-team" | no | false |
| merge_deploy_mode | This advanced alternate mode controls deployment after changes reach the default branch. The 'continue' output is 'false' only when the newest identifiable Branch Deploy deployment for the environment is active and its commit tree matches the current default branch. Missing, inactive, failed, pending, malformed, or different-tree deployment history sets 'continue' to 'true'. The 'environment' output is also set for subsequent steps. | no | false |
| unlock_on_merge_mode | This is an advanced option that is an alternate workflow bundled into this Action. You can optionally use this mode in a custom workflow to automatically release all locks that came from a pull request when the pull request is merged. This is useful if you want to ensure that locks are not left behind when a pull request is merged. | no | false |
| skip_completing | If set to true, bypass the entire post-action completion path. The workflow must manage final deployment status, comments, reactions, labels, and non-sticky lock cleanup. Default is false. | no | false |
| deploy_message_path | The repository-relative path to a trusted Markdown template for custom deployment messages. The file is fetched from the repository at the exact workflow SHA. Example: ".github/deployment_message.md" | no | .github/deployment_message.md |
| sticky_locks | If set to "true", locks will not be released after a deployment run completes. This applies to both successful, and failed deployments. Sticky locks are also known as "hubot style deployment locks". They will persist until they are manually released by a user, or if you configure another workflow with the "unlock on merge" mode to remove them automatically on PR merge. | no | false |
| sticky_locks_for_noop | If set to "true", then sticky_locks will also be used for noop deployments. This can be useful in some cases but it often leads to locks being left behind when users test noop deployments. | no | false |
| disable_lock | If set to "true", all deployment locking is disabled. Useful for workflows where concurrent deployments are safe (e.g. iOS/Android builds uploaded to TestFlight). When disabled, lock-related commands return an informational message instead of modifying lock state. | no | false |
| allow_sha_deployments | If set to "true", then you can deploy a specific sha instead of a branch. Example: ".deploy 1234567890abcdef1234567890abcdef12345678 to production" - This is dangerous and potentially unsafe, view the docs to learn more: https://github.com/github/branch-deploy/blob/main/docs/sha-deployments.md | no | false |
| disable_naked_commands | If set to "true", then naked commands will be disabled. Example: ".deploy" will not trigger a deployment. Instead, you must use ".deploy to production" to trigger a deployment. This is useful if you want to prevent accidental deployments from happening. Read more about naked commands here: https://github.com/github/branch-deploy/blob/main/docs/naked-commands.md | no | false |
| successful_deploy_labels | A comma separated list of labels to add to the pull request when a deployment is successful. Example: "deployed,success" | no | "" |
| successful_noop_labels | A comma separated list of labels to add to the pull request when a noop deployment is successful. Example: "noop,success" | no | "" |
| failed_deploy_labels | A comma separated list of labels to add to the pull request when a deployment fails. Example: "failed,deploy-failed" | no | "" |
| failed_noop_labels | A comma separated list of labels to add to the pull request when a noop deployment fails. Example: "failed,noop-failed" | no | "" |
| skip_successful_noop_labels_if_approved | Whether or not the post run logic should skip adding successful noop labels if the pull request is approved. This can be useful if you add a label such as "ready-for-review" after a .noop completes but want to skip adding that label in situations where the pull request is already approved. | no | false |
| skip_successful_deploy_labels_if_approved | Whether or not the post run logic should skip adding successful deploy labels if the pull request is approved. This can be useful if you add a label such as "ready-for-review" after a .deploy completes but want to skip adding that label in situations where the pull request is already approved. | no | false |
| enforced_deployment_order | A comma separated list of environments that must be deployed in a specific order. Example: `"development,staging,production"`. If this is set then you cannot deploy to latter environments unless the former ones have a successful and active deployment on the latest commit first. | no | "" |
| use_security_warnings | Whether or not to leave security related warnings in log messages during deployments. Default is "true" | no | true |
| allow_non_default_target_branch_deployments | Whether or not to allow deployments of pull requests that target a branch other than the default branch (aka stable branch) as their merge target. By default, this Action would reject the deployment of a branch named "feature-branch" if it was targeting "foo" instead of "main" (or whatever your default branch is). This option allows you to override that behavior and be able to deploy any branch in your repository regardless of the target branch. This option is potentially unsafe and should be used with caution as most default branches contain branch protection rules. Often times non-default branches do not contain these same branch protection rules. Follow along in this issue thread to learn more https://github.com/github/branch-deploy/issues/340 | no | false |
| deployment_confirmation | Whether or not to require an additional confirmation before a deployment can continue. Default is "false". If your project requires elevated security, it is highly recommended to enable this option - especially in open source projects where you might be deploying forks. docs/deployment-confirmation.md | no | false |
| deployment_confirmation_timeout | The number of seconds to wait for a deployment confirmation before timing out. Must be a positive integer. Default is "60" seconds (1 minute). | no | 60 |
Outputs
| name | description |
|---|---|
| continue | The string "true" if the deployment should continue, otherwise empty - Use this to conditionally control if your deployment should proceed or not |
| triggered | The string "true" if the trigger was found, otherwise the string "false" |
| comment_body | The comment body |
| issue_number | The issue number of the pull request (or issue) that was commented on |
| actor | The GitHub handle of the actor that invoked the IssueOps command |
| environment | The environment that has been selected for a deployment |
| params | The raw parameters that were passed into the deployment command (see param_separator) |
| parsed_params | A stringified JSON object of the parsed parameters that were passed into the deployment command |
| noop | The string "true" if the noop trigger was found, otherwise the string "false" - Use this to conditionally control whether your deployment runs as a noop or not |
| sha | The sha of the branch to be deployed |
| default_branch_tree_sha | The sha of the default branch tree (useful for subsequent workflow steps if they need to do commit comparisons) |
| base_ref | The base ref that the pull request is merging into |
| ref | The ref (branch or sha) to use with deployment |
| comment_id | The comment id which triggered this deployment |
| type | The type of trigger that was detected (examples: deploy, lock, unlock, lock-info-alias, help) |
| fork | The string "true" if the pull request is a fork, otherwise "false" |
| fork_ref | The true ref of the fork |
| fork_label | The API label field returned for the fork |
| fork_checkout | The console command presented in the GitHub UI to checkout a given fork locally |
| fork_full_name | The full name of the fork in "org/repo" format |
| deployment_id | The ID of the deployment created by running this action |
| environment_url | The environment URL detected and used for the deployment (sourced from the environment_urls input) |
| initial_reaction_id | The reaction id for the initial reaction on the trigger comment |
| initial_comment_id | The comment id for the "Deployment Triggered 🚀" comment created by the action |
| actor_handle | The handle of the user who triggered the action |
| global_lock_claimed | The string "true" if the global lock was claimed |
| global_lock_released | The string "true" if the global lock was released |
| unlocked_environments | Only exposed when using the "unlock on merge" mode - This output variable will contain a comma separated list of the environments that were unlocked |
| sha_deployment | If "allow_sha_deployments" is enabled, and a sha deployment is performed instead of a branch deployment, this output variable will contain the sha that was deployed. Otherwise, this output variable will be empty |
| review_decision | The pull request review status. Can be one of a few values - examples: APPROVED, REVIEW_REQUIRED, CHANGES_REQUESTED, skip_reviews, null |
| is_outdated | The string "true" if the branch is outdated, otherwise "false" |
| merge_state_status | The status of the merge state. Can be one of a few values - examples: "DIRTY", "DRAFT", "CLEAN", etc |
| commit_status | The status of the commit. Can be one of a few values - examples: "SUCCESS", null, "skip_ci", "PENDING", "FAILURE", or "UNAVAILABLE". UNAVAILABLE blocks deployment because CI status could not be verified. |
| approved_reviews_count | The number of approved reviews on the pull request |
| needs_to_be_deployed | A comma separated list of environments that need successful and active deployments before the current environment (that was requested) can be deployed. This output is tied to the "enforced_deployment_order" input option. |
| commit_verified | The string "true" if the commit has a verified signature, otherwise "false" |
| total_seconds | The total number of seconds that the deployment took to complete (Integer) |
| non_default_target_branch_used | The string "true" if the pull request is targeting a branch other than the default branch (aka stable branch) for the merge, otherwise unset |
| decision | The preferred main action decision output: continue, complete, stop, or failure |
| reason_code | The preferred stable machine-readable reason code for the main action decision |
| result | The preferred deterministic JSON string describing the versioned main action result |