github.com/ssube/gitlab-ci-multi-runner@v1.2.1-0.20160607142738-b8d1285632e6/docs/shells/README.md (about)

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