22 | ${node.getHeader().getTitle()}
23 |
24 |
6 | ${node.getContent()}
`, 13 | document: (node) => ` 14 | 15 | 16 | 17 | 18 | 19 | 20 |
22 |
24 | Enterprise
10 |
12 | 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/tcpnameThe name of your workflow will be displayed on your repository’s actions page.
68 |envA 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.
on EventThe 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 |When using the push and pull_request events, branches and tags allow to select or exclude (with the ! prefix) git references the workflow will run on, while paths specifies which files must have been modified in order to run the workflow.
If your rules are only made of exclusions, you can use branches-ignore, tags-ignore and paths-ignore. The -ignore form and its inclusive version cannot be mixed.
The types keyword enables you to narrow down activities (opened, created, edited…) causing the workflow to run. The list of available activities depends on the event.
A workflow trigger can also be scheduled:
92 |on:
98 | schedule:
99 | - cron: '*/15 * * * *'jobs CollectionA 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.
nameThe name of the job displayed on GitHub.
109 |needsIdentifies 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-onThe 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].
128 | Actions Cheat Sheet
131 |containerInstead 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-minutesThe maximum number of minutes to let a workflow run before GitHub automatically cancels it. Default: 360
145 |servicesAdditional 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.
stepsA 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.
nameSpecify the label to be displayed for this step in GitHub. It’s not required but does improve readability in the logs.
156 |usesSpecify 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 |uses: {owner}/{repo}@{ref} for actions in a public repository
uses: {owner}/{repo}/{path}@{ref} for actions in a subdirectory of a public repository
uses: ./path/to/dir for actions in a a subdirectory of the same repository
uses: docker://{image}:{tag} for actions on Docker Hub
uses: docker://{host}/{image}:{tag} for actions in a public registry
withA map of the input parameters defined by the action in its action.yml file. When the acion is container based, special parameter names are:
args, a string that defines the inputs passed to a Docker container’s ENTRYPOINT. It is used in place of the CMD instruction in a Dockerfile.
entrypoint, a string that defines or overrides the executable to run as the Docker container’s ENTRYPOINT.
ifPrevents a step from running unless a condition is met. The value is an expression without the ${{ … }} block.
runInstead 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.
strategyA 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-fastWhen set to true (default value), GitHub cancels all in-progress jobs if any of the matrix job fails.
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.
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:
key: The key used to save and search for a cache.
path: The file path (absolute or relative to the working directory) on the runner to cache or restore.
restore-keys: Optional - An ordered list of alternative keys to use for finding the cache if no cache hit occurred for key.
- 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-