10 | 
12 | !
19 |!
22 |Workflow Syntax
24 |Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. You must store workflow files in the .github/workflows/ directory of your repository. Each different YAML file corresponds to a different workflow.
name: My Workflow
28 | on:
29 | push:
30 | branches:
31 | - 'releases/*'
32 | - '!releases/**-alpha'
33 | env:
34 | message: 'conversation'
35 | my_token: ${{ secrets.GITHUB_TOKEN }}
36 | jobs:
37 | my_build:
38 | runs-on: ubuntu-latest
39 | steps:
40 | - name: Checking out our code
41 | uses: actions/checkout@master
42 | - name: Say something
43 | run: |
44 | echo "A little less ${message}"
45 | echo "A little more action"
46 | my_job:
47 | needs: my_build
48 | container:
49 | image: node:10.16-jessie
50 | env:
51 | NODE_ENV: development
52 | ports:
53 | - 80
54 | volumes:
55 | - my_docker_volume:/volume_mount
56 | options: --cpus 1
57 | services:
58 | redis:
59 | image: redis
60 | ports:
61 | - 6379/tcpWorkflow name
67 | The name of your workflow will be displayed on your repository’s actions page.
68 |Workflow, Job or Step env
71 | A map of environment variables which can be set at different scopes. Several environment variables are available by default (GITHUB_SHA, GITHUB_REF, GITHUB_EVENT_NAME, HOME, GITHUB_EVENT_PATH…) as well as a secret, GITHUB_TOKEN, which you can leverage for API calls or git commands through the secrets context.
!
76 |on Event
78 | The type event that triggers the workflow. You can provide a single event string, an array of events, or an event configuration map that restricts the execution of a workflow:
79 |-
81 |
-
82 |
When using the
83 |pushandpull_requestevents,branchesandtagsallow to select or exclude (with the!prefix) git references the workflow will run on, whilepathsspecifies which files must have been modified in order to run the workflow.
84 | -
85 |
If your rules are only made of exclusions, you can use
86 |branches-ignore,tags-ignoreandpaths-ignore. The-ignoreform and its inclusive version cannot be mixed.
87 | -
88 |
The
89 |typeskeyword enables you to narrow down activities (opened,created,edited…) causing the workflow to run. The list of available activities depends on the event.
90 | -
91 |
A workflow trigger can also be scheduled:
92 |
93 |
on:
98 | schedule:
99 | - cron: '*/15 * * * *'jobs Collection
105 | A workflow run is made up of one or more jobs identified by a unique job_id (my_build or my_job). Jobs run in parallel by default unless queued with the needs attribute. Each job runs in a fresh instance of the virtual environment specified by runs-on.
Job name
108 | The name of the job displayed on GitHub.
109 |needs
112 | Identifies any job 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.
113 |runs-on
116 | The type of virtual host machine to run the job on. Can be either a GitHub or self-hosted runner. Jobs can also run in user-specified containers (see: container). Available GitHub-hosted virtual machine types are ubuntu-latest, windows-latest, macOS-latest plus some other specific versions for each operating system, in the form of ubuntu-xx.xx, macOS-xx.xx or windows-xxxx. To specify a self-hosted runner for your job, configure runs-on in your workflow file with self-hosted runner labels. Example: [self-hosted, linux].
!
124 |
128 | Actions Cheat Sheet
131 |!
135 |!
138 |container
140 | Instead of running directly on a host selected with runs-on, a container can 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. This object has the following attributes: image, env, ports, volume and options.
timeout-minutes
144 | The maximum number of minutes to let a workflow run before GitHub automatically cancels it. Default: 360
145 |services
148 | Additional containers to host services for a job in a workflow. These are useful for creating databases or cache services. The runner on the virtual machine will automatically create a network and manage the lifecycle of the service containers. Each service is a named object in the services collection (redis or nginx for example) and can receive the same parameters than the container object.
Job steps
152 | A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action from your repository, a public repository, or an action published in a Docker registry. Each step runs in its own process in the virtual environment and has access to the workspace and filesystem.
Step name
155 | Specify the label to be displayed for this step in GitHub. It’s not required but does improve readability in the logs.
156 |uses
159 | Specify an action to run as part of a step in your job. You can use an action defined in the same repository as the workflow, a public repository elsewhere on GitHub, or in a published Docker container image. Including the version of the action you are using by specifying a Git ref, branch, SHA, or Docker tag is strongly recommended:
160 |-
162 |
-
163 |
164 |uses: {owner}/{repo}@{ref}for actions in a public repository
165 | -
166 |
167 |uses: {owner}/{repo}/{path}@{ref}for actions in a subdirectory of a public repository
168 | -
169 |
170 |uses: ./path/to/dirfor actions in a a subdirectory of the same repository
171 | -
172 |
173 |uses: docker://{image}:{tag}for actions on Docker Hub
174 | -
175 |
176 |uses: docker://{host}/{image}:{tag}for actions in a public registry
177 |
with
182 | A map of the input parameters defined by the action in its action.yml file. When the acion is container based, special parameter names are:
-
185 |
-
186 |
187 |args, a string that defines the inputs passed to a Docker container’sENTRYPOINT. It is used in place of theCMDinstruction in aDockerfile.
188 | -
189 |
190 |entrypoint, a string that defines or overrides the executable to run as the Docker container’sENTRYPOINT.
191 |
if
196 | Prevents a step from running unless a condition is met. The value is an expression without the ${{ … }} block.
!
202 |run
204 | Instead of running an existing action, a command line program can be run using the operating system’s shell. Each run keyword represents a new process and shell in the virtual environment. A specific shell can be selected with the shell attribute. Multiple commands can be run in a single shell instance using the | (pipe) operator.
Job strategy
208 | A build matrix strategy is a set of different configurations of the virtual environment. The job’ set of steps will be executed on each of these configurations. The following exemple specifies 3 nodejs versions on 2 operating systems:
209 |runs-on: ${{ matrix.os }}
212 | strategy:
213 | matrix:
214 | os: [ubuntu-16.04, ubuntu-18.04]
215 | node: [6, 8, 10]
216 | steps:
217 | - uses: actions/setup-node@v1
218 | with:
219 | node-version: ${{ matrix.node }}fail-fast
224 | When set to true (default value), GitHub cancels all in-progress jobs if any of the matrix job fails.
Context and expressions
229 |Expressions can be used to programmatically set variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators. With the exception of the if key, expressions are written in a ${{ … }} block. Contexts are objects providing access to runtime information. The following objects are available: github, job, steps, runner, secrets, strategy and matrix.
Artifact storage & Caching
233 |An artifact is a file or collection of files produced during a workflow run that can be stored and shared between jobs in a workflow run. Use actions actions/upload-artifact and actions/download-artifact with parameters name and path to manipulate artifacts. Artifacts can be downloaded through the Web interface for 90 days.
For dependencies and other commonly reused files across runs of a given workflow, use the actions/cache action with parameters:
-
237 |
-
238 |
239 |key: The key used to save and search for a cache.
240 | -
241 |
242 |path: The file path (absolute or relative to the working directory) on the runner to cache or restore.
243 | -
244 |
245 |restore-keys: Optional - An ordered list of alternative keys to use for finding the cache if no cache hit occurred for key.
246 |
- uses: actions/checkout@v1
251 | - name: Cache node modules
252 | uses: actions/cache@v1
253 | with:
254 | path: node_modules
255 | key: x-y-${{hashFiles('**/package-lock.json')}}
256 | restore-keys: |
257 | x-y-
258 | x-