docs: document deployment: false for environments without deployments (#60278)

Co-authored-by: Salil <salilsub@users.noreply.github.com>
Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>

Author: 5 people

content/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments.md

@@ -1,7 +1,7 @@
 ---
 title: Deploying with GitHub Actions
 shortTitle: Control deployments
-intro: Learn how to control deployments with features like environments and concurrency.
+intro: '{% data variables.product.prodname_actions %} gives you fine-grained control over deployments with environments, concurrency groups, and protection rules.'
 versions:
   fpt: '*'
   ghes: '*'
@@ -54,8 +54,54 @@ You can configure environments with protection rules and secrets. When a workflo
 
 Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. You can use concurrency so that an environment has a maximum of one deployment in progress and one deployment pending at a time. For more information about concurrency, see [AUTOTITLE](/actions/using-jobs/using-concurrency).
 
-> [!NOTE]
-> `concurrency` and `environment` are not connected. The concurrency value can be any string; it does not need to be an environment name. Additionally, if another workflow uses the same environment but does not specify concurrency, that workflow will not be subject to any concurrency rules.
+{% ifversion actions-environments-without-deployments %}
+
+## Using environments without deployments
+
+By default, when a workflow job references an environment, {% data variables.product.company_short %} creates a deployment object to track the deployment. You can opt out of deployment creation by setting `deployment` to `false` in the environment configuration. The valid values are `true` (default) and `false`. You can also use an expression, for example `deployment: {% raw %}${{ github.ref_name == 'main' }}{% endraw %}`.
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    environment:
+      name: staging
+      deployment: false
+    steps:
+      - name: run tests
+        env:
+          API_KEY: {% raw %}${{ secrets.API_KEY }}{% endraw %}
+        run: echo "Running tests with staging secrets"
+```
+
+When `deployment` is set to `false`:
+
+* The job has full access to environment secrets and variables.
+* No {% data variables.product.github %} deployment object is created—the deployment history for the environment is not updated.
+* Wait timer protection rules still apply—the job waits for the configured duration.
+* Required reviewers still apply—reviewers must still approve before the job runs.
+
+This is useful when you want to use environments for:
+
+* **Organizing secrets**—group related secrets under an environment name without creating deployment records.
+* **Access control**—restrict which branches can use certain secrets via environment branch policies, without deployment tracking.
+* **CI and testing jobs**—reference an environment for its configuration without adding noise to the deployment history.
+
+### Interaction with protection rules
+
+The `deployment` property controls which protection rules apply:
+
+| Protection rule | `deployment: true` (default) | `deployment: false` |
+|----------------|------------------------------|---------------------|
+| **None** | Deployment created, job runs | No deployment, job runs |
+| **Wait timer** | Wait timer enforced | Wait timer still enforced |
+| **Required reviewers** | Reviewers must approve | Reviewers must approve |
+| **Custom deployment protection rule app** | App webhook sent, must approve | **Job fails with error** |
+
+Custom deployment protection rules ({% data variables.product.prodname_github_apps %}) require a deployment object to function. If you set `deployment: false` on an environment that has custom deployment protection rules, the job will fail immediately with an annotation or error message explaining that the environment's protection rules are incompatible with `deployment: false`. Either remove `deployment: false` from your workflow, or remove the custom deployment protection rules from the environment.
+
+Note that `concurrency` and `environment` are not connected. The concurrency value can be any string; it does not need to be an environment name. Additionally, if another workflow uses the same environment but does not specify concurrency, that workflow will not be subject to any concurrency rules.
+{% endif %}
 
 For example, when the following workflow runs, it will be paused with the status `pending` if any job or workflow that uses the `production` concurrency group is in progress. It will also cancel any job or workflow that uses the `production` concurrency group and has the status `pending`. This means that there will be a maximum of one running and one pending job or workflow in that uses the `production` concurrency group.
 

content/actions/how-tos/deploy/configure-and-manage-deployments/create-custom-protection-rules.md

@@ -40,6 +40,12 @@ For general information about deployment protection rules, see [AUTOTITLE](/acti
 
 Once a workflow reaches a job that references an environment that has the custom deployment protection rule enabled, {% data variables.product.company_short %} sends a `POST` request to a URL you configure containing the `deployment_protection_rule` payload. You can write your deployment protection rule to automatically send REST API requests that approve or reject the deployment based on the `deployment_protection_rule` payload. Configure your REST API requests as follows.
 
+{% ifversion actions-environments-without-deployments %}
+
+Custom deployment protection rules are not compatible when a workflow job's environment is set to `deployment: false`. For more information, see [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments#interaction-with-protection-rules).
+
+{% endif %}
+
 1. Validate the incoming `POST` request. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks#validating-payloads-from-github).
 1. Use a JSON Web Token to authenticate as a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app#about-authentication-as-a-github-app).
 1. Using the installation ID from the `deployment_protection_rule` webhook payload, generate an install token. For more information, see [AUTOTITLE](/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-a-github-app).

content/actions/how-tos/write-workflows/choose-what-workflows-do/deploy-to-environment.md

@@ -47,3 +47,19 @@ You need to create an environment before you can use it in a workflow. See [AUTO
     * On the deployments page for the repository
     * In the visualization graph for the workflow run
     * (If a pull request triggers the workflow) As a "View deployment" button in the pull request timeline
+
+{% ifversion actions-environments-without-deployments %}
+
+1. Optionally, prevent a deployment object from being created by adding the `deployment` property. When set to `false`, the job still has access to environment secrets and variables, but no {% data variables.product.github %} deployment is created:
+
+    ```yaml copy
+    jobs:
+      JOB-ID:
+        environment:
+            name: ENVIRONMENT-NAME
+            deployment: false
+    ```
+
+    This is useful for CI or testing jobs that need environment secrets but aren't actually deploying anything. For more information, see [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments#using-environments-without-deployments).
+
+{% endif %}

data/features/actions-environments-without-deployments.yml

@@ -0,0 +1,5 @@
+# Reference: https://github.com/github/docs-internal/pull/60278
+# The `deployment` property on environments allows opting out of deployment creation.
+versions:
+  fpt: '*'
+  ghec: '*'

data/reusables/actions/jobs/section-using-environments-for-jobs.md

@@ -49,3 +49,20 @@ environment:
 ```
 
 {% endraw %}
+
+{% ifversion actions-environments-without-deployments %}
+
+### Example: Using an environment without creating a deployment
+
+Set `deployment` to `false` to use an environment's secrets and variables without creating a deployment object.
+
+```yaml
+environment:
+  name: testing
+  deployment: false
+```
+
+Setting `deployment: false` is not compatible with custom deployment protection rules.
+For more information, see [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments#using-environments-without-deployments).
+
+{% endif %}