GitLab-CI Keywords - Httqm's Docs

Use tags to select a specific runner from the list of all runners that are available for the project.
When you register a runner, you can specify the runner's tags, for example ruby, postgres, or development.
- To pick up and run a job, a runner must be assigned every tag listed in the job.

needs creates dependencies between jobs in a pipeline so that jobs run as soon as their dependencies are met, regardless of the pipeline's stagesstages configuration.

You can even configure a pipeline with no stages defined (effectively one large stage) and jobs still run in the proper order.

artifacts

artifacts are
- a list of files and directories that are attached to the job when it ends
  - these _may_ include log files, but artifacts are primarily designed to store files and directories created by a job after it finishes
- available in GitLab UI for download (unless they're too big)
artifacts is used to specify which files to save
by default, artifacts are collected + uploaded on successful jobs only. This is controlled by artifacts: when :
- on_success : upload artifacts when the job succeeds (default)
- on_failure : upload artifacts when the job fails
- always : always upload artifacts, whatever the job succeeds / fails (except if it times out)
by default, jobs in later stages automatically download all the artifacts created by jobs in earlier stages
- this can be controlled with dependencies and needs

example :

job:
  artifacts:
    paths:		relative to the project directory: $CI_PROJECT_DIR
      - binaries/
      - .config

this creates an artifact with .config and all the files in binaries

sets conditions for adding a job to a pipeline
there are
- when
- rules:when

when

is a job keyword
the word when has been somewhat misleading to me, since
- this directive doesn't explicitly define conditions to run a job
- instead, it defines a job type, which is one of (i.e. the corresponding job runs...) :
  - on_success / on_failure of previous jobs
  - always / never
  - manually (as a manual job)
defaults to when: on_success
example :
```
myJob:
  stage: 
  
  when: keyword
```

rules:when

like when, defines the job type BUT has some differences :
- it has more / different job type keywords
- it must be combined with one of :
  - changes
  - if
  - exists
  so that setting the job type becomes conditional
  omitting changes / if / exists
  - is actually setting no condition
  - is evaluated as true and the corresponding rule always matches

example :

myJob:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH	if this condition is true, add job to the pipeline
    - if: $CI_COMMIT_REF_NAME =~ /feature/		if this other condition is true, add job to the pipeline...
      when: delayed					... and make it a delayed job
    - when: manual					unconditionally make this a manual job
  script:
    - echo

rules:changes specifies that a job will only be added to a pipeline when specific files (specified as subkeys) are changed
rules:changes:paths is a synonymous of rules:changes (unclear why it exists, then. Possibly a legacy 🤷‍♀️)

`changes: pathSpec`

pathSpec can be
- an explicit list of files
- a single entry with wildcards
there is a logical OR within files listed by pathSpec
if any file matching pathSpec has changed, add the job to the pipeline
in case of empty pathSpec, changes evaluates to true for any change in the repository

`rules: conditions`

if: statement
- if statement is true, add the job to the pipeline
- if statement is true but it's combined with when: never : do not add the job to the pipeline
- if statement is false, check the next rules item (if any)
changes: pathSpec
exists: pathSpec
- if any file matching pathSpec exists, add the job to the pipeline
when: keyword

Subtlety about adding a job to a pipeline / NOT adding a job to a pipeline / running a job :

when conditions match, a job is added to a pipeline
once a job has been added to a pipeline, it will be run
but when conditions don't match, the job is not added to the pipeline
- which doesn't mean it forbids this job execution : it's just that conditions of the current rule are not met now to add this job to the pipeline
- but further rules may match and add it

tags

needs

artifacts

when

when

rules:when

changes

changes: pathSpec

rules

rules: conditions

Subtlety about adding a job to a pipeline / NOT adding a job to a pipeline / running a job :

`changes: pathSpec`

`rules: conditions`