diff options
Diffstat (limited to 'doc/ci/git_submodules.md')
-rw-r--r-- | doc/ci/git_submodules.md | 96 |
1 files changed, 27 insertions, 69 deletions
diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index d9a40c1feb6..01df4f63c92 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -5,38 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using Git submodules with GitLab CI +# Using Git submodules with GitLab CI/CD -> **Notes:** -> -> - GitLab 8.12 introduced a new [CI job permissions model](../user/project/new_ci_build_permissions_model.md) and you -> are encouraged to upgrade your GitLab instance if you haven't done already. -> If you are **not** using GitLab 8.12 or higher, you would need to work your way -> around submodules in order to access the sources of e.g., `gitlab.com/group/project` -> with the use of [SSH keys](ssh_keys/index.md). -> - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job -> can access. More information about how this system works can be found in the -> [Jobs permissions model](../user/permissions.md#job-permissions). -> - The HTTP(S) Git protocol [must be enabled](../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols) in your GitLab instance. +Use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to keep +a Git repository as a subdirectory of another Git repository. You can clone another +repository into your project and keep your commits separate. -## Configuring the `.gitmodules` file +## Configure the `.gitmodules` file -If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project probably has a file -named `.gitmodules`. +When you use Git submodules, your project should have a file named `.gitmodules`. +You might need to modify it to work in a GitLab CI/CD job. -Let's consider the following example: +For example, your `.gitmodules` configuration might look like the following if: -1. Your project is located at `https://gitlab.com/secret-group/my-project`. -1. To checkout your sources you usually use an SSH address like - `git@gitlab.com:secret-group/my-project.git`. -1. Your project depends on `https://gitlab.com/group/project`, which you want - to include as a submodule. - -If you are using GitLab 8.12+ and your submodule is on the same GitLab server, -you must update your `.gitmodules` file to use **relative URLs**. -Since Git allows the usage of relative URLs for your `.gitmodules` configuration, -this easily allows you to use HTTP(S) for cloning all your CI jobs and SSH -for all your local checkouts. The `.gitmodules` would look like: +- Your project is located at `https://gitlab.com/secret-group/my-project`. +- Your project depends on `https://gitlab.com/group/project`, which you want + to include as a submodule. +- You check out your sources with an SSH address like `git@gitlab.com:secret-group/my-project.git`. ```ini [submodule "project"] @@ -44,14 +29,16 @@ for all your local checkouts. The `.gitmodules` would look like: url = ../../group/project.git ``` -The above configuration instructs Git to automatically deduce the URL that -should be used when cloning sources. Whether you use HTTP(S) or SSH, Git uses -that same channel and it makes all your CI jobs use HTTP(S). -GitLab CI/CD only uses HTTP(S) for cloning your sources, and all your local -clones continue using SSH. +When your submodule is on the same GitLab server, you should use relative URLs in +your `.gitmodules` file. Then you can clone with HTTPS in all your CI/CD jobs. You +can also use SSH for all your local checkouts. + +The above configuration instructs Git to automatically deduce the URL to +use when cloning sources. Git uses the same configuration for both HTTPS and SSH. +GitLab CI/CD uses HTTPS for cloning your sources, and you can continue to use SSH +to clone locally. -For all other submodules not located on the same GitLab server, use the full -HTTP(S) protocol URL: +For submodules not located on the same GitLab server, use the full URL: ```ini [submodule "project-x"] @@ -59,45 +46,16 @@ HTTP(S) protocol URL: url = https://gitserver.com/group/project-x.git ``` -Once `.gitmodules` is correctly configured, you can move on to -[configuring your `.gitlab-ci.yml`](#using-git-submodules-in-your-ci-jobs). - -## Using Git submodules in your CI jobs +## Use Git submodules in CI/CD jobs -There are a few steps you need to take in order to make submodules work -correctly with your CI jobs: +To make submodules work correctly in CI/CD jobs: -1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file) - for the submodules located in the same GitLab server. -1. Next, if you are using `gitlab-runner` v1.10+, you can set the - `GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive` to tell - the runner to fetch your submodules before the job: +1. Make sure you use [relative URLs](#configure-the-gitmodules-file) + for submodules located in the same GitLab server. +1. You can set the `GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive` + to tell the runner to [fetch your submodules before the job](runners/README.md#git-submodule-strategy): ```yaml variables: GIT_SUBMODULE_STRATEGY: recursive ``` - - See the [GitLab Runner documentation](runners/README.md#git-submodule-strategy) - for more details about `GIT_SUBMODULE_STRATEGY`. - -1. If you are using an older version of `gitlab-runner`, then use - `git submodule sync/update` in `before_script`: - - ```yaml - before_script: - - git submodule sync --recursive - - git submodule update --init --recursive - ``` - - `--recursive` should be used in either both or none (`sync/update`) depending on - whether you have recursive submodules. - -The rationale to set the `sync` and `update` in `before_script` is because of -the way Git submodules work. On a fresh runner workspace, Git sets the -submodule URL including the token in `.git/config` -(or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current -remote URL. On subsequent jobs on the same runner, `.git/config` is cached -and already contains a full URL for the submodule, corresponding to the previous -job, and to **a token from a previous job**. `sync` allows to force updating -the full URL. |