You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/actions/creating-actions/metadata-syntax-for-github-actions.md
+40-40Lines changed: 40 additions & 40 deletions
Original file line number
Diff line number
Diff line change
@@ -22,19 +22,19 @@ Docker and JavaScript actions require a metadata file. The metadata filename mus
22
22
23
23
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)."
24
24
25
-
### **`name`**
25
+
### `name`
26
26
27
27
**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.
28
28
29
-
### **`author`**
29
+
### `author`
30
30
31
31
**Optional** The name of the action's author.
32
32
33
-
### **`description`**
33
+
### `description`
34
34
35
35
**Required** A short description of the action.
36
36
37
-
### **`inputs`**
37
+
### `inputs`
38
38
39
39
**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.
40
40
@@ -57,23 +57,23 @@ When you specify an input to an action in a workflow file or use a default input
57
57
58
58
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.
59
59
60
-
#### **`inputs.<input_id>`**
60
+
#### `inputs.<input_id>`
61
61
62
62
**Required** A `string` identifier to associate with the input. The value of `<input_id>` is a map of the input's metadata. The `<input_id>` must be a unique identifier within the `inputs` object. The `<input_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`.
63
63
64
-
#### **`inputs.<input_id>.description`**
64
+
#### `inputs.<input_id>.description`
65
65
66
66
**Required** A `string` description of the input parameter.
67
67
68
-
#### **`inputs.<input_id>.required`**
68
+
#### `inputs.<input_id>.required`
69
69
70
70
**Required** A `boolean` to indicate whether the action requires the input parameter. Set to `true` when the parameter is required.
71
71
72
-
#### **`inputs.<input_id>.default`**
72
+
#### `inputs.<input_id>.default`
73
73
74
74
**Optional** A `string` representing the default value. The default value is used when an input parameter isn't specified in a workflow file.
75
75
76
-
### **`outputs`**
76
+
### `outputs`
77
77
78
78
**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.
79
79
@@ -87,15 +87,15 @@ outputs:
87
87
description: 'The sum of the inputs'
88
88
```
89
89
90
-
#### **`outputs.<output_id>`**
90
+
#### `outputs.<output_id>`
91
91
92
92
**Required** A `string` identifier to associate with the output. The value of `<output_id>` is a map of the output's metadata. The `<output_id>` must be a unique identifier within the `outputs` object. The `<output_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`.
93
93
94
-
#### **`outputs.<output_id>.description`**
94
+
#### `outputs.<output_id>.description`
95
95
96
96
**Required** A `string` description of the output parameter.
97
97
98
-
### **`outputs`** for composite run steps actions
98
+
### `outputs` for composite run steps actions
99
99
100
100
**Optional** `outputs` use the same parameters as `outputs.<output_id>` and `outputs.<output_id>.description` (see "[`outputs` for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#outputs)"), but also includes the `value` token.
101
101
@@ -116,12 +116,12 @@ runs:
116
116
```
117
117
{% endraw %}
118
118
119
-
#### **`outputs.<output_id.value>`**
119
+
#### `outputs.<output_id.value>`
120
120
**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.
121
121
122
122
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)".
123
123
124
-
### **`runs`** for JavaScript actions
124
+
### `runs` for JavaScript actions
125
125
126
126
**Required** Configures the path to the action's code and the application used to execute the code.
127
127
@@ -133,15 +133,15 @@ runs:
133
133
main: 'main.js'
134
134
```
135
135
136
-
#### **`runs.using`**
136
+
#### `runs.using`
137
137
138
138
**Required** The application used to execute the code specified in [`main`](#runsmain).
139
139
140
-
#### **`runs.main`**
140
+
#### `runs.main`
141
141
142
142
**Required** The file that contains your action code. The application specified in [`using`](#runsusing) executes this file.
143
143
144
-
#### **`pre`**
144
+
#### `pre`
145
145
146
146
**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).
147
147
@@ -155,7 +155,7 @@ runs:
155
155
post: 'cleanup.js'
156
156
```
157
157
158
-
#### **`pre-if`**
158
+
#### `pre-if`
159
159
160
160
**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()`.
161
161
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:
167
167
pre-if: 'runner.os == linux'
168
168
```
169
169
170
-
#### **`post`**
170
+
#### `post`
171
171
172
172
**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.
173
173
@@ -182,7 +182,7 @@ runs:
182
182
183
183
The `post:` action always runs by default but you can override this using `post-if`.
184
184
185
-
#### **`post-if`**
185
+
#### `post-if`
186
186
187
187
**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()`.
188
188
@@ -193,19 +193,19 @@ For example, this `cleanup.js` will only run on Linux-based runners:
193
193
post-if: 'runner.os == linux'
194
194
```
195
195
196
-
### **`runs`** for composite run steps actions
196
+
### `runs` for composite run steps actions
197
197
198
198
**Required** Configures the path to the composite action, and the application used to execute the code.
199
199
200
-
#### **`runs.using`**
200
+
#### `runs.using`
201
201
202
202
**Required** To use a composite run steps action, set this to `"composite"`.
203
203
204
-
#### **`runs.steps`**
204
+
#### `runs.steps`
205
205
206
206
**Required** The run steps that you plan to run in this action.
207
207
208
-
##### **`runs.steps.run`**
208
+
##### `runs.steps.run`
209
209
210
210
**Required** The command you want to run. This can be inline or a script in your action repository:
211
211
```yaml
@@ -228,27 +228,27 @@ runs:
228
228
229
229
For more information, see "[`github context`](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)".
230
230
231
-
##### **`runs.steps.shell`**
231
+
##### `runs.steps.shell`
232
232
233
233
**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).
234
234
235
-
##### **`runs.steps.name`**
235
+
##### `runs.steps.name`
236
236
237
237
**Optional** The name of the composite run step.
238
238
239
-
##### **`runs.steps.id`**
239
+
##### `runs.steps.id`
240
240
241
241
**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)".
242
242
243
-
##### **`runs.steps.env`**
243
+
##### `runs.steps.env`
244
244
245
245
**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 "[email protected]" %}`echo "{name}={value}" >> $GITHUB_ENV`{% else %}`echo "::set-env name={name}::{value}"`{% endif %} in a composite run step.
246
246
247
-
##### **`runs.steps.working-directory`**
247
+
##### `runs.steps.working-directory`
248
248
249
249
**Optional** Specifies the working directory where the command is run.
250
250
251
-
### **`runs`** for Docker actions
251
+
### `runs` for Docker actions
252
252
253
253
**Required** Configures the image used for the Docker action.
254
254
@@ -268,11 +268,11 @@ runs:
268
268
image: 'docker://debian:stretch-slim'
269
269
```
270
270
271
-
#### **`runs.using`**
271
+
#### `runs.using`
272
272
273
273
**Required** You must set this value to `'docker'`.
274
274
275
-
#### **`pre-entrypoint`**
275
+
#### `pre-entrypoint`
276
276
277
277
**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).
278
278
@@ -290,21 +290,21 @@ runs:
290
290
entrypoint: 'main.sh'
291
291
```
292
292
293
-
#### **`runs.image`**
293
+
#### `runs.image`
294
294
295
295
**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.
296
296
297
-
#### **`runs.env`**
297
+
#### `runs.env`
298
298
299
299
**Optional** Specifies a key/value map of environment variables to set in the container environment.
300
300
301
-
#### **`runs.entrypoint`**
301
+
#### `runs.entrypoint`
302
302
303
303
**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.
304
304
305
305
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)."
306
306
307
-
#### **`post-entrypoint`**
307
+
#### `post-entrypoint`
308
308
309
309
**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).
310
310
@@ -318,7 +318,7 @@ runs:
318
318
post-entrypoint: 'cleanup.sh'
319
319
```
320
320
321
-
#### **`runs.args`**
321
+
#### `runs.args`
322
322
323
323
**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.
324
324
@@ -344,7 +344,7 @@ runs:
344
344
```
345
345
{% endraw %}
346
346
347
-
### **`branding`**
347
+
### `branding`
348
348
349
349
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).
350
350
@@ -356,11 +356,11 @@ branding:
356
356
color: 'green'
357
357
```
358
358
359
-
#### **`branding.color`**
359
+
#### `branding.color`
360
360
361
361
The background color of the badge. Can be one of: `white`, `yellow`, `blue`, `green`, `orange`, `red`, `purple`, or `gray-dark`.
362
362
363
-
#### **`branding.icon`**
363
+
#### `branding.icon`
364
364
365
365
The name of the [Feather](https://feathericons.com/) icon to use.
Copy file name to clipboardExpand all lines: content/actions/reference/context-and-expression-syntax-for-github-actions.md
+6-6Lines changed: 6 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -75,7 +75,7 @@ In order to use property dereference syntax, the property name must:
75
75
- start with `a-Z` or `_`.
76
76
- be followed by `a-Z` `0-9` `-` or `_`.
77
77
78
-
#### **`github` context**
78
+
#### `github` context
79
79
80
80
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)."
81
81
@@ -103,7 +103,7 @@ The `github` context contains information about the workflow run and the event t
103
103
| `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. |
104
104
| `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. |
105
105
106
-
#### **`env` context**
106
+
#### `env` context
107
107
108
108
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)."
109
109
@@ -117,7 +117,7 @@ You can only use the `env` context in the value of the `with` and `name` keys, o
117
117
| `env.<env name>` | `string` | The value of a specific environment variable. |
118
118
119
119
120
-
#### **`job` context**
120
+
#### `job` context
121
121
122
122
The `job` context contains information about the currently running job.
123
123
@@ -133,7 +133,7 @@ The `job` context contains information about the currently running job.
133
133
| `job.services.<service id>.ports` | `object` | The exposed ports of the service container. |
134
134
| `job.status` | `string` | The current status of the job. Possible values are `success`, `failure`, or `cancelled`. |
135
135
136
-
#### **`steps` context**
136
+
#### `steps` context
137
137
138
138
The `steps` context contains information about the steps in the current job that have already run.
139
139
@@ -145,7 +145,7 @@ The `steps` context contains information about the steps in the current job that
145
145
| `steps.<step id>.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`. |
146
146
| `steps.<step id>.outputs.<output name>` | `string` | The value of a specific output. |
147
147
148
-
#### **`runner` context**
148
+
#### `runner` context
149
149
150
150
The `runner` context contains information about the runner that is executing the current job.
151
151
@@ -155,7 +155,7 @@ The `runner` context contains information about the runner that is executing the
155
155
| `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. |
156
156
| `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)". |
157
157
158
-
#### **`needs` context**
158
+
#### `needs` context
159
159
160
160
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)."
0 commit comments