Merge branch 'main' into jules-4795
This commit is contained in:
Jules Parker
@@ -45,7 +45,7 @@ To use the value of an environment variable in a workflow file, you should use t
|
||||
|
||||
If you use the workflow file's `run` key to read environment variables from within the runner operating system (as shown in the example above), the variable is substituted in the runner operating system after the job is sent to the runner. For other parts of a workflow file, you must use the `env` context to read environment variables; this is because workflow keys (such as `if`) require the variable to be substituted during workflow processing before it is sent to the runner.
|
||||
|
||||
You can also use the {% ifversion fpt or ghes > 2.22 or ghae or ghec %}`GITHUB_ENV` environment file{% else %} `set-env` workflow command{% endif %} to set an environment variable that the following steps in a job can use. The {% ifversion fpt or ghes > 2.22 or ghae or ghec %}environment file{% else %} `set-env` command{% endif %} can be used directly by an action or as a shell command in a workflow file using the `run` keyword. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/reference/workflow-commands-for-github-actions/#setting-an-environment-variable)."
|
||||
You can also use the `GITHUB_ENV` environment file to set an environment variable that the following steps in a job can use. The environment file can be used directly by an action or as a shell command in a workflow file using the `run` keyword. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/reference/workflow-commands-for-github-actions/#setting-an-environment-variable)."
|
||||
|
||||
## Default environment variables
|
||||
|
||||
|
||||
@@ -63,7 +63,7 @@ Cron syntax has five fields separated by a space, and each field represents a un
|
||||
│ │ ┌───────────── day of the month (1 - 31)
|
||||
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
|
||||
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
|
||||
│ │ │ │ │
|
||||
│ │ │ │ │
|
||||
│ │ │ │ │
|
||||
│ │ │ │ │
|
||||
* * * * *
|
||||
@@ -90,7 +90,7 @@ Notifications for scheduled workflows are sent to the user who last modified the
|
||||
|
||||
## Manual events
|
||||
|
||||
You can manually trigger workflow runs. To trigger specific workflows in a repository, use the `workflow_dispatch` event. To trigger more than one workflow in a repository and create custom events and event types, use the `repository_dispatch` event.
|
||||
You can manually trigger workflow runs. To trigger specific workflows in a repository, use the `workflow_dispatch` event. To trigger more than one workflow in a repository and create custom events and event types, use the `repository_dispatch` event.
|
||||
|
||||
### `workflow_dispatch`
|
||||
|
||||
@@ -191,6 +191,28 @@ You can configure your workflow to run when webhook events are generated on {% d
|
||||
|
||||
Not all webhook events trigger workflows. For the complete list of available webhook events and their payloads, see "[Webhook events and payloads](/developers/webhooks-and-events/webhook-events-and-payloads)."
|
||||
|
||||
{% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-4968 %}
|
||||
### `branch_protection_rule`
|
||||
|
||||
Runs your workflow anytime the `branch_protection_rule` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the GraphQL API, see "[BranchProtectionRule]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/reference/objects#branchprotectionrule)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
|
||||
| --------------------- | -------------- | ------------ | -------------|
|
||||
| [`branch_protection_rule`](/webhooks/event-payloads/#branch_protection_rule) | - `created`<br/>- `edited`<br/>- `deleted` | Last commit on default branch | Default branch |
|
||||
|
||||
{% data reusables.developer-site.limit_workflow_to_activity_types %}
|
||||
|
||||
For example, you can run a workflow when a branch protection rule has been `created` or `deleted`.
|
||||
|
||||
```yaml
|
||||
on:
|
||||
branch_protection_rule:
|
||||
types: [created, deleted]
|
||||
```
|
||||
{% endif %}
|
||||
|
||||
### `check_run`
|
||||
|
||||
Runs your workflow anytime the `check_run` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check runs](/rest/reference/checks#runs)."
|
||||
@@ -590,7 +612,7 @@ Runs your workflow anytime the `pull_request` event occurs. {% data reusables.de
|
||||
|
||||
{% note %}
|
||||
|
||||
**Notes:**
|
||||
**Notes:**
|
||||
- By default, a workflow only runs when a `pull_request`'s activity type is `opened`, `synchronize`, or `reopened`. To trigger workflows for more activity types, use the `types` keyword.
|
||||
- Workflows will not run on `pull_request` activity if the pull request has a merge conflict. The merge conflict must be resolved first.
|
||||
|
||||
@@ -652,8 +674,6 @@ on:
|
||||
|
||||
{% data reusables.developer-site.pull_request_forked_repos_link %}
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
|
||||
### `pull_request_target`
|
||||
|
||||
This event runs in the context of the base of the pull request, rather than in the merge commit as the `pull_request` event does. This prevents executing unsafe workflow code from the head of the pull request that could alter your repository or steal any secrets you use in your workflow. This event allows you to do things like create workflows that label and comment on pull requests based on the contents of the event payload.
|
||||
@@ -678,8 +698,6 @@ on:
|
||||
types: [assigned, opened, synchronize, reopened]
|
||||
```
|
||||
|
||||
{% endif %}
|
||||
|
||||
### `push`
|
||||
|
||||
{% note %}
|
||||
@@ -786,8 +804,6 @@ on:
|
||||
types: [started]
|
||||
```
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
|
||||
### `workflow_run`
|
||||
|
||||
{% data reusables.webhooks.workflow_run_desc %}
|
||||
@@ -809,13 +825,11 @@ on:
|
||||
workflow_run:
|
||||
workflows: ["Run Tests"]
|
||||
branches: [main]
|
||||
types:
|
||||
types:
|
||||
- completed
|
||||
- requested
|
||||
```
|
||||
|
||||
{% endif %}
|
||||
|
||||
To run a workflow job conditionally based on the result of the previous workflow run, you can use the [`jobs.<job_id>.if`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idif) or [`jobs.<job_id>.steps[*].if`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsif) conditional combined with the `conclusion` of the previous run. For example:
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Reusing workflows
|
||||
shortTitle: Reusing workflows
|
||||
intro: 'Learn how to avoid duplication when creating a workflow by reusing existing workflows.'
|
||||
intro: Learn how to avoid duplication when creating a workflow by reusing existing workflows.
|
||||
miniTocMaxHeadingLevel: 3
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '>=3.4'
|
||||
ghae: 'issue-4757'
|
||||
ghae: issue-4757
|
||||
ghec: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
@@ -33,7 +33,7 @@ A workflow that uses another workflow is referred to as a "caller" workflow. The
|
||||
|
||||
If you reuse a workflow from a different repository, any actions in the called workflow run as if they were part of the caller workflow. For example, if the called workflow uses `actions/checkout`, the action checks out the contents of the repository that hosts the caller workflow, not the called workflow.
|
||||
|
||||
When a reusable workflow is triggered by a caller workflow, the `github` context is always associated with the caller workflow. For more information about the `github` context, see "[Context and expression syntax for GitHub Actions](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)."
|
||||
When a reusable workflow is triggered by a caller workflow, the `github` context is always associated with the caller workflow. The called workflow is automatically granted access to `github.token` and `secrets.GITHUB_TOKEN`. For more information about the `github` context, see "[Context and expression syntax for GitHub Actions](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)."
|
||||
|
||||
## Access to reusable workflows
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Sharing workflows, secrets, and runners with your organization
|
||||
title: 'Sharing workflows, secrets, and runners with your organization'
|
||||
shortTitle: Sharing workflows with your organization
|
||||
intro: 'Learn how you can use organization features to collaborate with your team, by sharing workflow templates, secrets, and self-hosted runners.'
|
||||
redirect_from:
|
||||
|
||||
@@ -213,7 +213,6 @@ In this diagram, you can see the workflow file you just created and how the {% d
|
||||
|
||||
|
||||
|
||||
|
||||
## Viewing the job's activity
|
||||
|
||||
Once your job has started running, you can {% ifversion fpt or ghes > 3.0 or ghae or ghec %}see a visualization graph of the run's progress and {% endif %}view each step's activity on {% data variables.product.prodname_dotcom %}.
|
||||
@@ -232,7 +231,7 @@ Once your job has started running, you can {% ifversion fpt or ghes > 3.0 or gha
|
||||
{% ifversion fpt or ghes > 3.0 or ghae or ghec %}
|
||||
1. View the results of each step.
|
||||
|
||||
{% elsif ghes > 2.22 %}
|
||||
{% elsif ghes %}
|
||||
1. Click on the job name to see the results of each step.
|
||||
|
||||
{% else %}
|
||||
|
||||
@@ -71,7 +71,6 @@ In addition to the usage limits, you must ensure that you use {% data variables.
|
||||
If you reuse a workflow, billing is always associated with the caller workflow. For more information see, "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
## Artifact and log retention policy
|
||||
|
||||
You can configure the artifact and log retention period for your repository, organization, or enterprise account.
|
||||
@@ -83,7 +82,6 @@ For more information, see:
|
||||
- "[Managing {% data variables.product.prodname_actions %} settings for a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository)"
|
||||
- "[Configuring the retention period for {% data variables.product.prodname_actions %} for artifacts and logs in your organization](/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization)"
|
||||
- "[Enforcing policies for {% data variables.product.prodname_actions %} in your enterprise](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-artifact-and-log-retention-in-your-enterprise)"
|
||||
{% endif %}
|
||||
|
||||
## Disabling or limiting {% data variables.product.prodname_actions %} for your repository or organization
|
||||
|
||||
@@ -94,7 +92,6 @@ For more information, see:
|
||||
- "[Disabling or limiting {% data variables.product.prodname_actions %} for your organization](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization)"
|
||||
- "[Enforcing policies for {% data variables.product.prodname_actions %} in your enterprise](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-github-actions-policies-for-your-enterprise#enforcing-a-policy-for-artifact-and-log-retention-in-your-enterprise)"
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
## Disabling and enabling workflows
|
||||
|
||||
You can enable and disable individual workflows in your repository on {% data variables.product.prodname_dotcom %}.
|
||||
@@ -102,4 +99,3 @@ You can enable and disable individual workflows in your repository on {% data va
|
||||
{% data reusables.actions.scheduled-workflows-disabled %}
|
||||
|
||||
For more information, see "[Disabling and enabling a workflow](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow)."
|
||||
{% endif %}
|
||||
|
||||
@@ -24,11 +24,7 @@ versions:
|
||||
|
||||
Actions can communicate with the runner machine to set environment variables, output values used by other actions, add debug messages to the output logs, and other tasks.
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
Most workflow commands use the `echo` command in a specific format, while others are invoked by writing to a file. For more information, see ["Environment files".](#environment-files)
|
||||
{% else %}
|
||||
Workflow commands use the `echo` command in a specific format.
|
||||
{% endif %}
|
||||
|
||||
``` bash
|
||||
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
|
||||
@@ -70,12 +66,12 @@ The following table shows which toolkit functions are available within a workflo
|
||||
|
||||
| Toolkit function | Equivalent workflow command |
|
||||
| ----------------- | ------------- |
|
||||
| `core.addPath` | {% ifversion fpt or ghes > 2.22 or ghae or ghec %}Accessible using environment file `GITHUB_PATH`{% else %} `add-path` {% endif %} |
|
||||
| `core.addPath` | Accessible using environment file `GITHUB_PATH` |
|
||||
| `core.debug` | `debug` |{% ifversion fpt or ghes > 3.2 or ghae-issue-4929 or ghec %}
|
||||
| `core.notice` | `notice` |{% endif %}
|
||||
| `core.error` | `error` |
|
||||
| `core.endGroup` | `endgroup` |
|
||||
| `core.exportVariable` | {% ifversion fpt or ghes > 2.22 or ghae or ghec %}Accessible using environment file `GITHUB_ENV`{% else %} `set-env` {% endif %} |
|
||||
| `core.exportVariable` | Accessible using environment file `GITHUB_ENV` |
|
||||
| `core.getInput` | Accessible using environment variable `INPUT_{NAME}` |
|
||||
| `core.getState` | Accessible using environment variable `STATE_{NAME}` |
|
||||
| `core.isDebug` | Accessible using environment variable `RUNNER_DEBUG` |
|
||||
@@ -86,22 +82,6 @@ The following table shows which toolkit functions are available within a workflo
|
||||
| `core.startGroup` | `group` |
|
||||
| `core.warning` | `warning` |
|
||||
|
||||
{% ifversion ghes < 3.0 %}
|
||||
## Setting an environment variable
|
||||
|
||||
```
|
||||
::set-env name={name}::{value}
|
||||
```
|
||||
|
||||
Creates or updates an environment variable for any steps running next in a job. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. Environment variables are case-sensitive and you can include punctuation.
|
||||
|
||||
### Example
|
||||
|
||||
``` bash
|
||||
echo "::set-env name=action_state::yellow"
|
||||
```
|
||||
{% endif %}
|
||||
|
||||
## Setting an output parameter
|
||||
|
||||
```
|
||||
@@ -118,22 +98,6 @@ Optionally, you can also declare output parameters in an action's metadata file.
|
||||
echo "::set-output name=action_fruit::strawberry"
|
||||
```
|
||||
|
||||
{% ifversion ghes < 3.0 %}
|
||||
## Adding a system path
|
||||
|
||||
```
|
||||
::add-path::{path}
|
||||
```
|
||||
|
||||
Prepends a directory to the system `PATH` variable for all subsequent actions in the current job. The currently running action cannot access the new path variable.
|
||||
|
||||
### Example
|
||||
|
||||
``` bash
|
||||
echo "::add-path::/path/to/dir"
|
||||
```
|
||||
{% endif %}
|
||||
|
||||
## Setting a debug message
|
||||
|
||||
```
|
||||
@@ -302,7 +266,6 @@ The `STATE_processID` variable is then exclusively available to the cleanup scri
|
||||
console.log("The running PID from the main action is: " + process.env.STATE_processID);
|
||||
```
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
## Environment Files
|
||||
|
||||
During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files are exposed via environment variables. You will need to use UTF-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines.
|
||||
@@ -386,4 +349,3 @@ This example demonstrates how to add the user `$HOME/.local/bin` directory to `P
|
||||
``` bash
|
||||
echo "$HOME/.local/bin" >> $GITHUB_PATH
|
||||
```
|
||||
{% endif %}
|
||||
|
||||
@@ -541,7 +541,6 @@ environment:
|
||||
{% endraw %}
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% ifversion fpt or ghae-next or ghes > 3.1 or ghec %}
|
||||
## `jobs.<job_id>.concurrency`
|
||||
|
||||
@@ -955,7 +954,6 @@ steps:
|
||||
|
||||
The command used, `perl` in this example, must be installed on the runner.
|
||||
|
||||
|
||||
{% ifversion ghae %}For instructions on how to make sure your {% data variables.actions.hosted_runner %} has the required software installed, see "[Creating custom images](/actions/using-github-hosted-runners/creating-custom-images)."
|
||||
{% else %}
|
||||
For information about the software included on GitHub-hosted runners, see "[Specifications for GitHub-hosted runners](/actions/reference/specifications-for-github-hosted-runners#supported-software)."
|
||||
@@ -1274,9 +1272,7 @@ jobs:
|
||||
|
||||
## `jobs.<job_id>.container.image`
|
||||
|
||||
The Docker image to use as the container to run the action. The value can be the Docker Hub image name or a {% ifversion ghes < 3.0 %}public{% endif %} registry name.
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
The Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.
|
||||
|
||||
## `jobs.<job_id>.container.credentials`
|
||||
|
||||
@@ -1293,7 +1289,6 @@ container:
|
||||
password: ${{ secrets.ghcr_token }}
|
||||
```
|
||||
{% endraw %}
|
||||
{% endif %}
|
||||
|
||||
## `jobs.<job_id>.container.env`
|
||||
|
||||
@@ -1364,9 +1359,7 @@ services:
|
||||
|
||||
## `jobs.<job_id>.services.<service_id>.image`
|
||||
|
||||
The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a {% ifversion ghes < 3.0 %}public{% endif %} registry name.
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
|
||||
The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.
|
||||
|
||||
## `jobs.<job_id>.services.<service_id>.credentials`
|
||||
|
||||
@@ -1389,7 +1382,6 @@ services:
|
||||
password: ${{ secrets.DOCKER_PASSWORD }}
|
||||
```
|
||||
{% endraw %}
|
||||
{% endif %}
|
||||
|
||||
## `jobs.<job_id>.services.<service_id>.env`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user