diff --git a/content/actions/creating-actions/metadata-syntax-for-github-actions.md b/content/actions/creating-actions/metadata-syntax-for-github-actions.md index 5dfc38f38048..38e8526fed0f 100644 --- a/content/actions/creating-actions/metadata-syntax-for-github-actions.md +++ b/content/actions/creating-actions/metadata-syntax-for-github-actions.md @@ -22,19 +22,19 @@ Docker and JavaScript actions require a metadata file. The metadata filename mus Action metadata files use YAML syntax. If you're new to YAML, you can read "[Learn YAML in five minutes](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes)." -### **`name`** +### `name` **Required** The name of your action. {% data variables.product.prodname_dotcom %} displays the `name` in the **Actions** tab to help visually identify actions in each job. -### **`author`** +### `author` **Optional** The name of the action's author. -### **`description`** +### `description` **Required** A short description of the action. -### **`inputs`** +### `inputs` **Optional** Input parameters allow you to specify data that the action expects to use during runtime. {% data variables.product.prodname_dotcom %} stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids. @@ -57,23 +57,23 @@ When you specify an input to an action in a workflow file or use a default input For example, if a workflow defined the numOctocats and octocatEyeColor inputs, the action code could read the values of the inputs using the `INPUT_NUMOCTOCATS` and `INPUT_OCTOCATEYECOLOR` environment variables. -#### **`inputs.`** +#### `inputs.` **Required** A `string` identifier to associate with the input. The value of `` is a map of the input's metadata. The `` must be a unique identifier within the `inputs` object. The `` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. -#### **`inputs..description`** +#### `inputs..description` **Required** A `string` description of the input parameter. -#### **`inputs..required`** +#### `inputs..required` **Required** A `boolean` to indicate whether the action requires the input parameter. Set to `true` when the parameter is required. -#### **`inputs..default`** +#### `inputs..default` **Optional** A `string` representing the default value. The default value is used when an input parameter isn't specified in a workflow file. -### **`outputs`** +### `outputs` **Optional** Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions. For example, if you had an action that performed the addition of two inputs (x + y = z), the action could output the sum (z) for other actions to use as an input. @@ -87,15 +87,15 @@ outputs: description: 'The sum of the inputs' ``` -#### **`outputs.`** +#### `outputs.` **Required** A `string` identifier to associate with the output. The value of `` is a map of the output's metadata. The `` must be a unique identifier within the `outputs` object. The `` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. -#### **`outputs..description`** +#### `outputs..description` **Required** A `string` description of the output parameter. -### **`outputs`** for composite run steps actions +### `outputs` for composite run steps actions **Optional** `outputs` use the same parameters as `outputs.` and `outputs..description` (see "[`outputs` for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#outputs)"), but also includes the `value` token. @@ -116,12 +116,12 @@ runs: ``` {% endraw %} -#### **`outputs.`** +#### `outputs.` **Required** The value that the output parameter will be mapped to. You can set this to a `string` or an expression with context. For example, you can use the `steps` context to set the `value` of an output to the output value of a step. For more information on how to use context and expression syntax, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)". -### **`runs`** for JavaScript actions +### `runs` for JavaScript actions **Required** Configures the path to the action's code and the application used to execute the code. @@ -133,15 +133,15 @@ runs: main: 'main.js' ``` -#### **`runs.using`** +#### `runs.using` **Required** The application used to execute the code specified in [`main`](#runsmain). -#### **`runs.main`** +#### `runs.main` **Required** The file that contains your action code. The application specified in [`using`](#runsusing) executes this file. -#### **`pre`** +#### `pre` **Optional** Allows you to run a script at the start of a job, before the `main:` action begins. For example, you can use `pre:` to run a prerequisite setup script. The application specified with the [`using`](#runsusing) syntax will execute this file. The `pre:` action always runs by default but you can override this using [`pre-if`](#pre-if). @@ -155,7 +155,7 @@ runs: post: 'cleanup.js' ``` -#### **`pre-if`** +#### `pre-if` **Optional** Allows you to define conditions for the `pre:` action execution. The `pre:` action will only run if the conditions in `pre-if` are met. If not set, then `pre-if` defaults to `always()`. Note that the `step` context is unavailable, as no steps have run yet. @@ -167,7 +167,7 @@ In this example, `cleanup.js` only runs on Linux-based runners: pre-if: 'runner.os == linux' ``` -#### **`post`** +#### `post` **Optional** Allows you to run a script at the end of a job, once the `main:` action has completed. For example, you can use `post:` to terminate certain processes or remove unneeded files. The application specified with the [`using`](#runsusing) syntax will execute this file. @@ -182,7 +182,7 @@ runs: The `post:` action always runs by default but you can override this using `post-if`. -#### **`post-if`** +#### `post-if` **Optional** Allows you to define conditions for the `post:` action execution. The `post:` action will only run if the conditions in `post-if` are met. If not set, then `post-if` defaults to `always()`. @@ -193,19 +193,19 @@ For example, this `cleanup.js` will only run on Linux-based runners: post-if: 'runner.os == linux' ``` -### **`runs`** for composite run steps actions +### `runs` for composite run steps actions **Required** Configures the path to the composite action, and the application used to execute the code. -#### **`runs.using`** +#### `runs.using` **Required** To use a composite run steps action, set this to `"composite"`. -#### **`runs.steps`** +#### `runs.steps` **Required** The run steps that you plan to run in this action. -##### **`runs.steps.run`** +##### `runs.steps.run` **Required** The command you want to run. This can be inline or a script in your action repository: ```yaml @@ -228,27 +228,27 @@ runs: For more information, see "[`github context`](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)". -##### **`runs.steps.shell`** +##### `runs.steps.shell` **Required** The shell where you want to run the command. You can use any of the shells listed [here](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell). -##### **`runs.steps.name`** +##### `runs.steps.name` **Optional** The name of the composite run step. -##### **`runs.steps.id`** +##### `runs.steps.id` **Optional** A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)". -##### **`runs.steps.env`** +##### `runs.steps.env` **Optional** Sets a `map` of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}`echo "{name}={value}" >> $GITHUB_ENV`{% else %}`echo "::set-env name={name}::{value}"`{% endif %} in a composite run step. -##### **`runs.steps.working-directory`** +##### `runs.steps.working-directory` **Optional** Specifies the working directory where the command is run. -### **`runs`** for Docker actions +### `runs` for Docker actions **Required** Configures the image used for the Docker action. @@ -268,11 +268,11 @@ runs: image: 'docker://debian:stretch-slim' ``` -#### **`runs.using`** +#### `runs.using` **Required** You must set this value to `'docker'`. -#### **`pre-entrypoint`** +#### `pre-entrypoint` **Optional** Allows you to run a script before the `entrypoint` action begins. For example, you can use `pre-entrypoint:` to run a prerequisite setup script. {% data variables.product.prodname_actions %} uses `docker run` to launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the main `entrypoint` container, and any states you require must be accessed in either the workspace, `HOME`, or as a `STATE_` variable. The `pre-entrypoint:` action always runs by default but you can override this using [`pre-if`](#pre-if). @@ -290,21 +290,21 @@ runs: entrypoint: 'main.sh' ``` -#### **`runs.image`** +#### `runs.image` **Required** The Docker image to use as the container to run the action. The value can be the Docker base image name, a local `Dockerfile` in your repository, or a public image in Docker Hub or another registry. To reference a `Dockerfile` local to your repository, use a path relative to your action metadata file. The `docker` application will execute this file. -#### **`runs.env`** +#### `runs.env` **Optional** Specifies a key/value map of environment variables to set in the container environment. -#### **`runs.entrypoint`** +#### `runs.entrypoint` **Optional** Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Use `entrypoint` when the `Dockerfile` does not specify an `ENTRYPOINT` or you want to override the `ENTRYPOINT` instruction. If you omit `entrypoint`, the commands you specify in the Docker `ENTRYPOINT` instruction will execute. The Docker `ENTRYPOINT` instruction has a _shell_ form and _exec_ form. The Docker `ENTRYPOINT` documentation recommends using the _exec_ form of the `ENTRYPOINT` instruction. For more information about how the `entrypoint` executes, see "[Dockerfile support for {% data variables.product.prodname_actions %}](/actions/creating-actions/dockerfile-support-for-github-actions/#entrypoint)." -#### **`post-entrypoint`** +#### `post-entrypoint` **Optional** Allows you to run a cleanup script once the `runs.entrypoint` action has completed. {% data variables.product.prodname_actions %} uses `docker run` to launch this action. Because {% data variables.product.prodname_actions %} runs the script inside a new container using the same base image, the runtime state is different from the main `entrypoint` container. You can access any state you need in either the workspace, `HOME`, or as a `STATE_` variable. The `post-entrypoint:` action always runs by default but you can override this using [`post-if`](#post-if). @@ -318,7 +318,7 @@ runs: post-entrypoint: 'cleanup.sh' ``` -#### **`runs.args`** +#### `runs.args` **Optional** An array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up. @@ -344,7 +344,7 @@ runs: ``` {% endraw %} -### **`branding`** +### `branding` You can use a color and [Feather](https://feathericons.com/) icon to create a badge to personalize and distinguish your action. Badges are shown next to your action name in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions). @@ -356,11 +356,11 @@ branding: color: 'green' ``` -#### **`branding.color`** +#### `branding.color` The background color of the badge. Can be one of: `white`, `yellow`, `blue`, `green`, `orange`, `red`, `purple`, or `gray-dark`. -#### **`branding.icon`** +#### `branding.icon` The name of the [Feather](https://feathericons.com/) icon to use. diff --git a/content/actions/reference/context-and-expression-syntax-for-github-actions.md b/content/actions/reference/context-and-expression-syntax-for-github-actions.md index ba100c62739c..fd33466bb50d 100644 --- a/content/actions/reference/context-and-expression-syntax-for-github-actions.md +++ b/content/actions/reference/context-and-expression-syntax-for-github-actions.md @@ -75,7 +75,7 @@ In order to use property dereference syntax, the property name must: - start with `a-Z` or `_`. - be followed by `a-Z` `0-9` `-` or `_`. -#### **`github` context** +#### `github` context The `github` context contains information about the workflow run and the event that triggered the run. You can read most of the `github` context data in environment variables. For more information about environment variables, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)." @@ -103,7 +103,7 @@ The `github` context contains information about the workflow run and the event t | `github.workflow` | `string` | The name of the workflow. If the workflow file doesn't specify a `name`, the value of this property is the full path of the workflow file in the repository. | | `github.workspace` | `string` | The default working directory for steps and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. | -#### **`env` context** +#### `env` context The `env` context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env)." @@ -117,7 +117,7 @@ You can only use the `env` context in the value of the `with` and `name` keys, o | `env.` | `string` | The value of a specific environment variable. | -#### **`job` context** +#### `job` context The `job` context contains information about the currently running job. @@ -133,7 +133,7 @@ The `job` context contains information about the currently running job. | `job.services..ports` | `object` | The exposed ports of the service container. | | `job.status` | `string` | The current status of the job. Possible values are `success`, `failure`, or `cancelled`. | -#### **`steps` context** +#### `steps` context The `steps` context contains information about the steps in the current job that have already run. @@ -145,7 +145,7 @@ The `steps` context contains information about the steps in the current job that | `steps..outcome` | `string` | The result of a completed step before [`continue-on-error`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error) is applied. Possible values are `success`, `failure`, `cancelled`, or `skipped`. When a `continue-on-error` step fails, the `outcome` is `failure`, but the final `conclusion` is `success`. | | `steps..outputs.` | `string` | The value of a specific output. | -#### **`runner` context** +#### `runner` context The `runner` context contains information about the runner that is executing the current job. @@ -155,7 +155,7 @@ The `runner` context contains information about the runner that is executing the | `runner.temp` | `string` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. | | `runner.tool_cache` | `string` | The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". | -#### **`needs` context** +#### `needs` context The `needs` context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)." diff --git a/content/actions/reference/workflow-syntax-for-github-actions.md b/content/actions/reference/workflow-syntax-for-github-actions.md index 5ba82777f199..47ff0e94fc51 100644 --- a/content/actions/reference/workflow-syntax-for-github-actions.md +++ b/content/actions/reference/workflow-syntax-for-github-actions.md @@ -21,17 +21,17 @@ Workflow files use YAML syntax, and must have either a `.yml` or `.yaml` file ex You must store workflow files in the `.github/workflows` directory of your repository. -### **`name`** +### `name` The name of your workflow. {% data variables.product.prodname_dotcom %} displays the names of your workflows on your repository's actions page. If you omit `name`, {% data variables.product.prodname_dotcom %} sets it to the workflow file path relative to the root of the repository. -### **`on`** +### `on` **Required** The name of the {% data variables.product.prodname_dotcom %} event that triggers the workflow. You can provide a single event `string`, `array` of events, `array` of event `types`, or an event configuration `map` that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see "[Events that trigger workflows](/articles/events-that-trigger-workflows)." {% data reusables.github-actions.actions-on-examples %} -### **`on..types`** +### `on..types` Selects the types of activity that will trigger a workflow run. Most GitHub events are triggered by more than one type of activity. For example, the event for the release resource is triggered when a release is `published`, `unpublished`, `created`, `edited`, `deleted`, or `prereleased`. The `types` keyword enables you to narrow down activity that causes the workflow to run. When only one activity type triggers a webhook event, the `types` keyword is unnecessary. @@ -45,7 +45,7 @@ on: types: [published, created, edited] ``` -### **`on..`** +### `on..` When using the `push` and `pull_request` events, you can configure a workflow to run on specific branches or tags. For a `pull_request` event, only branches and tags on the base are evaluated. If you define only `tags` or only `branches`, the workflow won't run for events affecting the undefined Git ref. @@ -112,7 +112,7 @@ on: - '!releases/**-alpha' ``` -### **`on..paths`** +### `on..paths` When using the `push` and `pull_request` events, you can configure a workflow to run when at least one file does not match `paths-ignore` or at least one modified file matches the configured `paths`. Path filters are not evaluated for pushes to tags. @@ -179,13 +179,13 @@ The filter determines if a workflow should run by evaluating the changed files a For more information, see "[About comparing branches in pull requests](/articles/about-comparing-branches-in-pull-requests)." -### **`on.schedule`** +### `on.schedule` {% data reusables.repositories.actions-scheduled-workflow-example %} For more information about cron syntax, see "[Events that trigger workflows](/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#scheduled-events)." -### **`env`** +### `env` A `map` of environment variables that are available to all jobs and steps in the workflow. You can also set environment variables that are only available to a job or step. For more information, see [`jobs..env`](#jobsjob_idenv) and [`jobs..steps.env`](#jobsjob_idstepsenv). @@ -198,13 +198,13 @@ env: SERVER: production ``` -### **`defaults`** +### `defaults` A `map` of default settings that will apply to all jobs in the workflow. You can also set default settings that are only available to a job. For more information, see [`jobs..defaults`](#jobsjob_iddefaults). {% data reusables.github-actions.defaults-override %} -### **`defaults.run`** +### `defaults.run` You can provide default `shell` and `working-directory` options for all [`run`](#jobsjob_idstepsrun) steps in a workflow. You can also set default settings for `run` that are only available to a job. For more information, see [`jobs..defaults.run`](#jobsjob_iddefaultsrun). You cannot use contexts or expressions in this keyword. @@ -219,7 +219,7 @@ defaults: working-directory: scripts ``` -### **`jobs`** +### `jobs` A workflow run is made up of one or more jobs. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the `jobs..needs` keyword. @@ -229,7 +229,7 @@ You can run an unlimited number of jobs as long as you are within the workflow u If you need to find the unique identifier of a job running in a workflow run, you can use the {% data variables.product.prodname_dotcom %} API. For more information, see "[Workflow Jobs](/rest/reference/actions#workflow-jobs)." -### **`jobs.`** +### `jobs.` Each job must have an id to associate with the job. The key `job_id` is a string and its value is a map of the job's configuration data. You must replace `` with a string that is unique to the `jobs` object. The `` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. @@ -243,11 +243,11 @@ jobs: name: My second job ``` -### **`jobs..name`** +### `jobs..name` The name of the job displayed on {% data variables.product.prodname_dotcom %}. -### **`jobs..needs`** +### `jobs..needs` Identifies any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional statement that causes the job to continue. @@ -270,7 +270,7 @@ The jobs in this example run sequentially: 2. `job2` 3. `job3` -### **`jobs..runs-on`** +### `jobs..runs-on` **Required** The type of machine to run the job on. The machine can be either a {% data variables.product.prodname_dotcom %}-hosted runner or a self-hosted runner. @@ -286,7 +286,7 @@ Available {% data variables.product.prodname_dotcom %}-hosted runner types are: {% data reusables.github-actions.ubuntu-runner-preview %} -##### **Example** +##### Example ```yaml runs-on: ubuntu-latest @@ -298,7 +298,7 @@ For more information, see "[Virtual environments for {% data variables.product.p {% data reusables.github-actions.self-hosted-runner-labels-runs-on %} -##### **Example** +##### Example ```yaml runs-on: [self-hosted, linux] @@ -306,7 +306,7 @@ runs-on: [self-hosted, linux] For more information, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners)" and "[Using self-hosted runners in a workflow](/github/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow)." -### **`jobs..outputs`** +### `jobs..outputs` A `map` of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see [`jobs..needs`](#jobsjob_idneeds). @@ -314,7 +314,7 @@ Job outputs are strings, and job outputs containing expressions are evaluated on To use job outputs in a dependent job, you can use the `needs` context. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#needs-context)." -#### **Example** +#### Example {% raw %} ```yaml @@ -338,13 +338,13 @@ jobs: ``` {% endraw %} -### **`jobs..env`** +### `jobs..env` A `map` of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see [`env`](#env) and [`jobs..steps.env`](#jobsjob_idstepsenv). {% data reusables.repositories.actions-env-var-note %} -#### **Example** +#### Example ```yaml jobs: @@ -353,13 +353,13 @@ jobs: FIRST_NAME: Mona ``` -### **`jobs..defaults`** +### `jobs..defaults` A `map` of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow. For more information, see [`defaults`](#defaults). {% data reusables.github-actions.defaults-override %} -### **`jobs..defaults.run`** +### `jobs..defaults.run` Provide default `shell` and `working-directory` to all `run` steps in the job. Context and expression are not allowed in this section. @@ -379,13 +379,13 @@ jobs: working-directory: scripts ``` -### **`jobs..if`** +### `jobs..if` You can use the `if` conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional. {% data reusables.github-actions.expression-syntax-if %} For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." -### **`jobs..steps`** +### `jobs..steps` A job contains a sequence of tasks called `steps`. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. {% data variables.product.prodname_dotcom %} provides built-in steps to set up and complete a job. @@ -415,11 +415,11 @@ jobs: ``` {% endraw %} -#### **`jobs..steps.id`** +#### `jobs..steps.id` A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." -#### **`jobs..steps.if`** +#### `jobs..steps.if` You can use the `if` conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional. @@ -449,11 +449,11 @@ steps: uses: actions/heroku@1.0.0 ``` -#### **`jobs..steps.name`** +#### `jobs..steps.name` A name for your step to display on {% data variables.product.prodname_dotcom %}. -#### **`jobs..steps.uses`** +#### `jobs..steps.uses` Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a [published Docker container image](https://hub.docker.com/). @@ -556,7 +556,7 @@ jobs: uses: docker://gcr.io/cloud-builders/gradle ``` -#### **`jobs..steps.run`** +#### `jobs..steps.run` Runs command-line programs using the operating system's shell. If you do not provide a `name`, the step name will default to the text specified in the `run` command. @@ -661,7 +661,7 @@ For built-in shell keywords, we provide the following defaults that are executed - There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script. - `cmd.exe` will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous `sh` and `pwsh` default behavior and is the `cmd.exe` default, so this behavior remains intact. -#### **`jobs..steps.with`** +#### `jobs..steps.with` A `map` of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with `INPUT_` and converted to upper case. @@ -681,7 +681,7 @@ jobs: last_name: Octocat ``` -#### **`jobs..steps.with.args`** +#### `jobs..steps.with.args` A `string` that defines the inputs for a Docker container. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up. An `array of strings` is not supported by this parameter. @@ -704,7 +704,7 @@ The `args` are used in place of the `CMD` instruction in a `Dockerfile`. If you 1. Use defaults that allow using the action without specifying any `args`. 1. If the action exposes a `--help` flag, or something similar, use that as the default to make your action self-documenting. -#### **`jobs..steps.with.entrypoint`** +#### `jobs..steps.with.entrypoint` Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Unlike the Docker `ENTRYPOINT` instruction which has a shell and exec form, `entrypoint` keyword accepts only a single string defining the executable to be run. @@ -720,7 +720,7 @@ steps: The `entrypoint` keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs. -#### **`jobs..steps.env`** +#### `jobs..steps.env` Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see [`env`](#env) and [`jobs..env`](#jobsjob_idenv). @@ -741,23 +741,23 @@ steps: ``` {% endraw %} -#### **`jobs..steps.continue-on-error`** +#### `jobs..steps.continue-on-error` Prevents a job from failing when a step fails. Set to `true` to allow a job to pass when this step fails. -#### **`jobs..steps.timeout-minutes`** +#### `jobs..steps.timeout-minutes` The maximum number of minutes to run the step before killing the process. -### **`jobs..timeout-minutes`** +### `jobs..timeout-minutes` The maximum number of minutes to let a job run before {% data variables.product.prodname_dotcom %} automatically cancels it. Default: 360 -### **`jobs..strategy`** +### `jobs..strategy` A strategy creates a build matrix for your jobs. You can define different variations of an environment to run each job in. -#### **`jobs..strategy.matrix`** +#### `jobs..strategy.matrix` You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure. @@ -882,11 +882,11 @@ You can add custom environment variables for each test combination by using the {% data reusables.github-actions.matrix-variable-example %} -### **`jobs..strategy.fail-fast`** +### `jobs..strategy.fail-fast` When set to `true`, {% data variables.product.prodname_dotcom %} cancels all in-progress jobs if any `matrix` job fails. Default: `true` -### **`jobs..strategy.max-parallel`** +### `jobs..strategy.max-parallel` The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. By default, {% data variables.product.prodname_dotcom %} will maximize the number of jobs run in parallel depending on the available runners on {% data variables.product.prodname_dotcom %}-hosted virtual machines. @@ -895,7 +895,7 @@ strategy: max-parallel: 2 ``` -### **`jobs..continue-on-error`** +### `jobs..continue-on-error` Prevents a workflow run from failing when a job fails. Set to `true` to allow a workflow run to pass when this job fails. @@ -920,7 +920,7 @@ strategy: ``` {% endraw %} -### **`jobs..container`** +### `jobs..container` A container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts. @@ -950,12 +950,12 @@ jobs: container: node:10.16-jessie ``` -#### **`jobs..container.image`** +#### `jobs..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 {% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.23" %}public{% endif %} registry name. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} -#### **`jobs..container.credentials`** +#### `jobs..container.credentials` {% data reusables.actions.registry-credentials %} @@ -972,15 +972,15 @@ container: {% endraw %} {% endif %} -#### **`jobs..container.env`** +#### `jobs..container.env` Sets a `map` of environment variables in the container. -#### **`jobs..container.ports`** +#### `jobs..container.ports` Sets an `array` of ports to expose on the container. -#### **`jobs..container.volumes`** +#### `jobs..container.volumes` Sets an `array` of volumes for the container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host. @@ -999,11 +999,11 @@ volumes: - /source/directory:/destination/directory ``` -#### **`jobs..container.options`** +#### `jobs..container.options` Additional Docker container resource options. For a list of options, see "[`docker create` options](https://docs.docker.com/engine/reference/commandline/create/#options)." -### **`jobs..services`** +### `jobs..services` {% data reusables.github-actions.docker-container-os-support %} @@ -1033,12 +1033,12 @@ services: - 6379/tcp ``` -#### **`jobs..services..image`** +#### `jobs..services..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 {% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.23" %}public{% endif %} registry name. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} -#### **`jobs..services..credentials`** +#### `jobs..services..credentials` {% data reusables.actions.registry-credentials %} @@ -1061,15 +1061,15 @@ services: {% endraw %} {% endif %} -#### **`jobs..services..env`** +#### `jobs..services..env` Sets a `map` of environment variables in the service container. -#### **`jobs..services..ports`** +#### `jobs..services..ports` Sets an `array` of ports to expose on the service container. -#### **`jobs..services..volumes`** +#### `jobs..services..volumes` Sets an `array` of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host. @@ -1088,7 +1088,7 @@ volumes: - /source/directory:/destination/directory ``` -#### **`jobs..services..options`** +#### `jobs..services..options` Additional Docker container resource options. For a list of options, see "[`docker create` options](https://docs.docker.com/engine/reference/commandline/create/#options)." diff --git a/data/reusables/github-actions/actions-on-examples.md b/data/reusables/github-actions/actions-on-examples.md index beea3062f56b..06efe2e4ea43 100644 --- a/data/reusables/github-actions/actions-on-examples.md +++ b/data/reusables/github-actions/actions-on-examples.md @@ -1,18 +1,18 @@ -##### **Example using a single event** +##### Example using a single event ```yaml # Triggered when code is pushed to any branch in a repository on: push ``` -##### **Example using a list of events** +##### Example using a list of events ```yaml # Triggers the workflow on push or pull request events on: [push, pull_request] ``` -##### **Example using multiple events with activity types or configuration** +##### Example using multiple events with activity types or configuration If you need to specify activity types or configuration for an event, you must configure each event separately. You must append a colon (`:`) to all events, including events without configuration.