gitlab.com/jfprevost/gitlab-runner-notlscheck@v11.11.4+incompatible/docs/shells/index.md (about)

     1  # Shells supported by GitLab Runner
     2  
     3  GitLab Runner implements a few shell script generators that allow to execute
     4  builds on different systems.
     5  
     6  ## Overview
     7  
     8  The shell scripts contain commands to execute all steps of the build:
     9  
    10  1. `git clone`
    11  1. Restore the build cache
    12  1. Build commands
    13  1. Update the build cache
    14  1. Generate and upload the build artifacts
    15  
    16  The shells don't have any configuration options. The build steps are received
    17  from the commands defined in the [`script` directive in `.gitlab-ci.yml`][script].
    18  
    19  The currently supported shells are:
    20  
    21  | Shell         | Description |
    22  | --------------| ----------- |
    23  | `bash`        | Bash (Bourne-shell) shell. All commands executed in Bash context (default for all Unix systems) |
    24  | `sh`          | Sh (Bourne-shell) shell. All commands executed in Sh context (fallback for `bash` for all Unix systems) |
    25  | `cmd`         | Windows Batch script. All commands are executed in Batch context (default for Windows) |
    26  | `powershell`  | Windows PowerShell script. All commands are executed in PowerShell context |
    27  
    28  If you want to select a particular shell to use other than the default, you will need to [specify the shell](../executors/shell.md#selecting-your-shell) in your `config.toml` file.
    29  
    30  ## Sh/Bash shells
    31  
    32  This is the default shell used on all Unix based systems. The bash script used
    33  in `.gitlab-ci.yml` is executed by piping the shell script to one of the
    34  following commands:
    35  
    36  ```bash
    37  # This command is used if the build should be executed in context
    38  # of another user (the shell executor)
    39  cat generated-bash-script | su --shell /bin/bash --login user
    40  
    41  # This command is used if the build should be executed using
    42  # the current user, but in a login environment
    43  cat generated-bash-script | /bin/bash --login
    44  
    45  # This command is used if the build should be executed in
    46  # a Docker environment
    47  cat generated-bash-script | /bin/bash
    48  ```
    49  
    50  ## Windows Batch
    51  
    52  This is the default shell used on Windows. Windows Batch doesn't support
    53  executing the build in context of another user.
    54  
    55  The generated Batch script is executed by saving its content to file and
    56  passing the file name to the following command:
    57  
    58  ```bash
    59  cmd /Q /C generated-windows-batch.cmd
    60  ```
    61  
    62  This is how an example batch script looks like:
    63  
    64  ```bash
    65  @echo off
    66  setlocal enableextensions
    67  setlocal enableDelayedExpansion
    68  set nl=^
    69  
    70  
    71  echo Running on %COMPUTERNAME%...
    72  
    73  call :prescript
    74  IF !errorlevel! NEQ 0 exit /b !errorlevel!
    75  
    76  call :buildscript
    77  IF !errorlevel! NEQ 0 exit /b !errorlevel!
    78  
    79  call :postscript
    80  IF !errorlevel! NEQ 0 exit /b !errorlevel!
    81  
    82  goto :EOF
    83  :prescript
    84  SET CI=true
    85  SET CI_COMMIT_REF=db45ad9af9d7af5e61b829442fd893d96e31250c
    86  SET CI_COMMIT_BEFORE_SHA=d63117656af6ff57d99e50cc270f854691f335ad
    87  SET CI_COMMIT_REF_NAME=master
    88  SET CI_JOB_ID=1
    89  SET CI_REPOSITORY_URL=http://gitlab.example.com/group/project.git
    90  SET CI_PROJECT_ID=1
    91  SET CI_PROJECT_DIR=Z:\Gitlab\tests\test\builds\0\project-1
    92  SET CI_SERVER=yes
    93  SET CI_SERVER_NAME=GitLab CI
    94  SET CI_SERVER_VERSION=
    95  SET CI_SERVER_REVISION=
    96  SET GITLAB_CI=true
    97  md "C:\\GitLab-Runner\\builds\\0\\project-1.tmp" 2>NUL 1>NUL
    98  echo multiline!nl!tls!nl!chain > C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO
    99  SET GIT_SSL_CAINFO=C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO
   100  md "C:\\GitLab-Runner\\builds\\0\\project-1.tmp" 2>NUL 1>NUL
   101  echo multiline!nl!tls!nl!chain > C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE
   102  SET CI_SERVER_TLS_CA_FILE=C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE
   103  echo Cloning repository...
   104  rd /s /q "C:\GitLab-Runner\builds\0\project-1" 2>NUL 1>NUL
   105  "git" "clone" "http://gitlab.example.com/group/project.git" "Z:\Gitlab\tests\test\builds\0\project-1"
   106  IF !errorlevel! NEQ 0 exit /b !errorlevel!
   107  
   108  cd /D "C:\GitLab-Runner\builds\0\project-1"
   109  IF !errorlevel! NEQ 0 exit /b !errorlevel!
   110  
   111  echo Checking out db45ad9a as master...
   112  "git" "checkout" "db45ad9af9d7af5e61b829442fd893d96e31250c"
   113  IF !errorlevel! NEQ 0 exit /b !errorlevel!
   114  
   115  IF EXIST "..\..\..\cache\project-1\pages\master\cache.tgz" (
   116    echo Restoring cache...
   117    "gitlab-runner-windows-amd64.exe" "extract" "--file" "..\..\..\cache\project-1\pages\master\cache.tgz"
   118    IF !errorlevel! NEQ 0 exit /b !errorlevel!
   119  
   120  ) ELSE (
   121    IF EXIST "..\..\..\cache\project-1\pages\master\cache.tgz" (
   122      echo Restoring cache...
   123      "gitlab-runner-windows-amd64.exe" "extract" "--file" "..\..\..\cache\project-1\pages\master\cache.tgz"
   124      IF !errorlevel! NEQ 0 exit /b !errorlevel!
   125  
   126    )
   127  )
   128  goto :EOF
   129  
   130  :buildscript
   131  SET CI=true
   132  SET CI_COMMIT_REF=db45ad9af9d7af5e61b829442fd893d96e31250c
   133  SET CI_COMMIT_BEFORE_SHA=d63117656af6ff57d99e50cc270f854691f335ad
   134  SET CI_COMMIT_REF_NAME=master
   135  SET CI_JOB_ID=1
   136  SET CI_REPOSITORY_URL=Z:\Gitlab\tests\test
   137  SET CI_PROJECT_ID=1
   138  SET CI_PROJECT_DIR=Z:\Gitlab\tests\test\builds\0\project-1
   139  SET CI_SERVER=yes
   140  SET CI_SERVER_NAME=GitLab CI
   141  SET CI_SERVER_VERSION=
   142  SET CI_SERVER_REVISION=
   143  SET GITLAB_CI=true
   144  md "C:\\GitLab-Runner\\builds\\0\\project-1.tmp" 2>NUL 1>NUL
   145  echo multiline!nl!tls!nl!chain > C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO
   146  SET GIT_SSL_CAINFO=C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO
   147  md "C:\\GitLab-Runner\\builds\\0\\project-1.tmp" 2>NUL 1>NUL
   148  echo multiline!nl!tls!nl!chain > C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE
   149  SET CI_SERVER_TLS_CA_FILE=C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE
   150  cd /D "C:\GitLab-Runner\builds\0\project-1"
   151  IF !errorlevel! NEQ 0 exit /b !errorlevel!
   152  
   153  echo $ echo true
   154  echo true
   155  goto :EOF
   156  
   157  :postscript
   158  SET CI=true
   159  SET CI_COMMIT_REF=db45ad9af9d7af5e61b829442fd893d96e31250c
   160  SET CI_COMMIT_BEFORE_SHA=d63117656af6ff57d99e50cc270f854691f335ad
   161  SET CI_COMMIT_REF_NAME=master
   162  SET CI_JOB_ID=1
   163  SET CI_REPOSITORY_URL=Z:\Gitlab\tests\test
   164  SET CI_PROJECT_ID=1
   165  SET CI_PROJECT_DIR=Z:\Gitlab\tests\test\builds\0\project-1
   166  SET CI_SERVER=yes
   167  SET CI_SERVER_NAME=GitLab CI
   168  SET CI_SERVER_VERSION=
   169  SET CI_SERVER_REVISION=
   170  SET GITLAB_CI=true
   171  md "C:\\GitLab-Runner\\builds\\0\\project-1.tmp" 2>NUL 1>NUL
   172  echo multiline!nl!tls!nl!chain > C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO
   173  SET GIT_SSL_CAINFO=C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO
   174  md "C:\\GitLab-Runner\\builds\\0\\project-1.tmp" 2>NUL 1>NUL
   175  echo multiline!nl!tls!nl!chain > C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE
   176  SET CI_SERVER_TLS_CA_FILE=C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE
   177  cd /D "C:\GitLab-Runner\builds\0\project-1"
   178  IF !errorlevel! NEQ 0 exit /b !errorlevel!
   179  
   180  echo Archiving cache...
   181  "gitlab-runner-windows-amd64.exe" "archive" "--file" "..\..\..\cache\project-1\pages\master\cache.tgz" "--path" "vendor"
   182  IF !errorlevel! NEQ 0 exit /b !errorlevel!
   183  
   184  goto :EOF
   185  ```
   186  
   187  ## PowerShell
   188  
   189  PowerShell doesn't support executing the build in context of another user.
   190  
   191  The generated PowerShell script is executed by saving it content to a file and
   192  passing the file name to the following command:
   193  
   194  ```bash
   195  powershell -noprofile -noninteractive -executionpolicy Bypass -command generated-windows-powershell.ps1
   196  ```
   197  
   198  This is how an example powershell script looks like:
   199  
   200  ```bash
   201  $ErrorActionPreference = "Stop"
   202  
   203  echo "Running on $env:computername..."
   204  
   205  & {
   206    $CI="true"
   207    $env:CI=$CI
   208    $CI_COMMIT_REF="db45ad9af9d7af5e61b829442fd893d96e31250c"
   209    $env:CI_COMMIT_REF=$CI_COMMIT_REF
   210    $CI_COMMIT_BEFORE_SHA="d63117656af6ff57d99e50cc270f854691f335ad"
   211    $env:CI_COMMIT_BEFORE_SHA=$CI_COMMIT_BEFORE_SHA
   212    $CI_COMMIT_REF_NAME="master"
   213    $env:CI_COMMIT_REF_NAME=$CI_COMMIT_REF_NAME
   214    $CI_JOB_ID="1"
   215    $env:CI_JOB_ID=$CI_JOB_ID
   216    $CI_REPOSITORY_URL="Z:\Gitlab\tests\test"
   217    $env:CI_REPOSITORY_URL=$CI_REPOSITORY_URL
   218    $CI_PROJECT_ID="1"
   219    $env:CI_PROJECT_ID=$CI_PROJECT_ID
   220    $CI_PROJECT_DIR="Z:\Gitlab\tests\test\builds\0\project-1"
   221    $env:CI_PROJECT_DIR=$CI_PROJECT_DIR
   222    $CI_SERVER="yes"
   223    $env:CI_SERVER=$CI_SERVER
   224    $CI_SERVER_NAME="GitLab CI"
   225    $env:CI_SERVER_NAME=$CI_SERVER_NAME
   226    $CI_SERVER_VERSION=""
   227    $env:CI_SERVER_VERSION=$CI_SERVER_VERSION
   228    $CI_SERVER_REVISION=""
   229    $env:CI_SERVER_REVISION=$CI_SERVER_REVISION
   230    $GITLAB_CI="true"
   231    $env:GITLAB_CI=$GITLAB_CI
   232    $GIT_SSL_CAINFO=""
   233    md "C:\GitLab-Runner\builds\0\project-1.tmp" -Force | out-null
   234    $GIT_SSL_CAINFO | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
   235    $GIT_SSL_CAINFO="C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
   236    $env:GIT_SSL_CAINFO=$GIT_SSL_CAINFO
   237    $CI_SERVER_TLS_CA_FILE=""
   238    md "C:\GitLab-Runner\builds\0\project-1.tmp" -Force | out-null
   239    $CI_SERVER_TLS_CA_FILE | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
   240    $CI_SERVER_TLS_CA_FILE="C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
   241    $env:CI_SERVER_TLS_CA_FILE=$CI_SERVER_TLS_CA_FILE
   242    echo "Cloning repository..."
   243    if( (Get-Command -Name Remove-Item2 -Module NTFSSecurity -ErrorAction SilentlyContinue) -and (Test-Path "C:\GitLab-Runner\builds\0\project-1" -PathType Container) ) {
   244      Remove-Item2 -Force -Recurse "C:\GitLab-Runner\builds\0\project-1"
   245    } elseif(Test-Path "C:\GitLab-Runner\builds\0\project-1") {
   246      Remove-Item -Force -Recurse "C:\GitLab-Runner\builds\0\project-1"
   247    }
   248  
   249    & "git" "clone" "https://gitlab.com/group/project.git" "Z:\Gitlab\tests\test\builds\0\project-1"
   250    if(!$?) { Exit $LASTEXITCODE }
   251  
   252    cd "C:\GitLab-Runner\builds\0\project-1"
   253    if(!$?) { Exit $LASTEXITCODE }
   254  
   255    echo "Checking out db45ad9a as master..."
   256    & "git" "checkout" "db45ad9af9d7af5e61b829442fd893d96e31250c"
   257    if(!$?) { Exit $LASTEXITCODE }
   258  
   259    if(Test-Path "..\..\..\cache\project-1\pages\master\cache.tgz" -PathType Leaf) {
   260      echo "Restoring cache..."
   261      & "gitlab-runner-windows-amd64.exe" "extract" "--file" "..\..\..\cache\project-1\pages\master\cache.tgz"
   262      if(!$?) { Exit $LASTEXITCODE }
   263  
   264    } else {
   265      if(Test-Path "..\..\..\cache\project-1\pages\master\cache.tgz" -PathType Leaf) {
   266        echo "Restoring cache..."
   267        & "gitlab-runner-windows-amd64.exe" "extract" "--file" "..\..\..\cache\project-1\pages\master\cache.tgz"
   268        if(!$?) { Exit $LASTEXITCODE }
   269  
   270      }
   271    }
   272  }
   273  if(!$?) { Exit $LASTEXITCODE }
   274  
   275  & {
   276    $CI="true"
   277    $env:CI=$CI
   278    $CI_COMMIT_REF="db45ad9af9d7af5e61b829442fd893d96e31250c"
   279    $env:CI_COMMIT_REF=$CI_COMMIT_REF
   280    $CI_COMMIT_BEFORE_SHA="d63117656af6ff57d99e50cc270f854691f335ad"
   281    $env:CI_COMMIT_BEFORE_SHA=$CI_COMMIT_BEFORE_SHA
   282    $CI_COMMIT_REF_NAME="master"
   283    $env:CI_COMMIT_REF_NAME=$CI_COMMIT_REF_NAME
   284    $CI_JOB_ID="1"
   285    $env:CI_JOB_ID=$CI_JOB_ID
   286    $CI_REPOSITORY_URL="Z:\Gitlab\tests\test"
   287    $env:CI_REPOSITORY_URL=$CI_REPOSITORY_URL
   288    $CI_PROJECT_ID="1"
   289    $env:CI_PROJECT_ID=$CI_PROJECT_ID
   290    $CI_PROJECT_DIR="Z:\Gitlab\tests\test\builds\0\project-1"
   291    $env:CI_PROJECT_DIR=$CI_PROJECT_DIR
   292    $CI_SERVER="yes"
   293    $env:CI_SERVER=$CI_SERVER
   294    $CI_SERVER_NAME="GitLab CI"
   295    $env:CI_SERVER_NAME=$CI_SERVER_NAME
   296    $CI_SERVER_VERSION=""
   297    $env:CI_SERVER_VERSION=$CI_SERVER_VERSION
   298    $CI_SERVER_REVISION=""
   299    $env:CI_SERVER_REVISION=$CI_SERVER_REVISION
   300    $GITLAB_CI="true"
   301    $env:GITLAB_CI=$GITLAB_CI
   302    $GIT_SSL_CAINFO=""
   303    md "C:\GitLab-Runner\builds\0\project-1.tmp" -Force | out-null
   304    $GIT_SSL_CAINFO | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
   305    $GIT_SSL_CAINFO="C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
   306    $env:GIT_SSL_CAINFO=$GIT_SSL_CAINFO
   307    $CI_SERVER_TLS_CA_FILE=""
   308    md "C:\GitLab-Runner\builds\0\project-1.tmp" -Force | out-null
   309    $CI_SERVER_TLS_CA_FILE | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
   310    $CI_SERVER_TLS_CA_FILE="C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
   311    $env:CI_SERVER_TLS_CA_FILE=$CI_SERVER_TLS_CA_FILE
   312    cd "C:\GitLab-Runner\builds\0\project-1"
   313    if(!$?) { Exit $LASTEXITCODE }
   314  
   315    echo "`$ echo true"
   316    echo true
   317  }
   318  if(!$?) { Exit $LASTEXITCODE }
   319  
   320  & {
   321    $CI="true"
   322    $env:CI=$CI
   323    $CI_COMMIT_REF="db45ad9af9d7af5e61b829442fd893d96e31250c"
   324    $env:CI_COMMIT_REF=$CI_COMMIT_REF
   325    $CI_COMMIT_BEFORE_SHA="d63117656af6ff57d99e50cc270f854691f335ad"
   326    $env:CI_COMMIT_BEFORE_SHA=$CI_COMMIT_BEFORE_SHA
   327    $CI_COMMIT_REF_NAME="master"
   328    $env:CI_COMMIT_REF_NAME=$CI_COMMIT_REF_NAME
   329    $CI_JOB_ID="1"
   330    $env:CI_JOB_ID=$CI_JOB_ID
   331    $CI_REPOSITORY_URL="Z:\Gitlab\tests\test"
   332    $env:CI_REPOSITORY_URL=$CI_REPOSITORY_URL
   333    $CI_PROJECT_ID="1"
   334    $env:CI_PROJECT_ID=$CI_PROJECT_ID
   335    $CI_PROJECT_DIR="Z:\Gitlab\tests\test\builds\0\project-1"
   336    $env:CI_PROJECT_DIR=$CI_PROJECT_DIR
   337    $CI_SERVER="yes"
   338    $env:CI_SERVER=$CI_SERVER
   339    $CI_SERVER_NAME="GitLab CI"
   340    $env:CI_SERVER_NAME=$CI_SERVER_NAME
   341    $CI_SERVER_VERSION=""
   342    $env:CI_SERVER_VERSION=$CI_SERVER_VERSION
   343    $CI_SERVER_REVISION=""
   344    $env:CI_SERVER_REVISION=$CI_SERVER_REVISION
   345    $GITLAB_CI="true"
   346    $env:GITLAB_CI=$GITLAB_CI
   347    $GIT_SSL_CAINFO=""
   348    md "C:\GitLab-Runner\builds\0\project-1.tmp" -Force | out-null
   349    $GIT_SSL_CAINFO | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
   350    $GIT_SSL_CAINFO="C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
   351    $env:GIT_SSL_CAINFO=$GIT_SSL_CAINFO
   352    $CI_SERVER_TLS_CA_FILE=""
   353    md "C:\GitLab-Runner\builds\0\project-1.tmp" -Force | out-null
   354    $CI_SERVER_TLS_CA_FILE | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
   355    $CI_SERVER_TLS_CA_FILE="C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
   356    $env:CI_SERVER_TLS_CA_FILE=$CI_SERVER_TLS_CA_FILE
   357    cd "C:\GitLab-Runner\builds\0\project-1"
   358    if(!$?) { Exit $LASTEXITCODE }
   359  
   360    echo "Archiving cache..."
   361    & "gitlab-runner-windows-amd64.exe" "archive" "--file" "..\..\..\cache\project-1\pages\master\cache.tgz" "--path" "vendor"
   362    if(!$?) { Exit $LASTEXITCODE }
   363  
   364  }
   365  if(!$?) { Exit $LASTEXITCODE }
   366  ```
   367  
   368  [script]: http://doc.gitlab.com/ce/ci/yaml/README.html#script