kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Merge branch 'docs-code-block-style-8' into 'master'

Browse source 
Fix whitespace in ci docs

See merge request gitlab-org/gitlab-ce!30655
This commit is contained in:
Evan Read 2019-08-01 02:29:17 +00:00
commit 28d95c0ca6
7 changed files with 449 additions and 445 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

178
doc/ci/ci_cd_for_external_repos/bitbucket_integration.md
View file

@ -14,9 +14,9 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:
1. In GitLab create a **CI/CD for external repo**, select **Repo by URL** and
create the project.
![Create project](img/external_repository.png)
![Create project](img/external_repository.png)
GitLab will import the repository and enable [Pull Mirroring][pull-mirroring].
GitLab will import the repository and enable [Pull Mirroring][pull-mirroring].
1. In GitLab create a
[Personal Access Token](../../user/profile/personal_access_tokens.md)
@ -26,19 +26,19 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:
1. In Bitbucket, from **Settings > Webhooks**, create a new web hook to notify
GitLab of new commits.
The web hook URL should be set to the GitLab API to trigger pull mirroring,
using the Personal Access Token we just generated for authentication.
The web hook URL should be set to the GitLab API to trigger pull mirroring,
using the Personal Access Token we just generated for authentication.
```text
https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN>
```
```text
https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN>
```
The web hook Trigger should be set to 'Repository Push'.
The web hook Trigger should be set to 'Repository Push'.
![Bitbucket Cloud webhook](img/bitbucket_webhook.png)
![Bitbucket Cloud webhook](img/bitbucket_webhook.png)
After saving, test the web hook by pushing a change to your Bitbucket
repository.
After saving, test the web hook by pushing a change to your Bitbucket
repository.
1. In Bitbucket, create an **App Password** from **Bitbucket Settings > App
Passwords** to authenticate the build status script setting commit build
@ -49,104 +49,104 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:
1. In GitLab, from **Settings > CI/CD > Environment variables**, add variables to allow
communication with Bitbucket via the Bitbucket API:
`BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above.
`BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above.
`BITBUCKET_USERNAME`: the username of the Bitbucket account.
`BITBUCKET_USERNAME`: the username of the Bitbucket account.
`BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ.
`BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ.
`BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ.
`BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ.
1. In Bitbucket, add a script to push the pipeline status to Bitbucket.
> Note: changes made in GitLab will be overwritten by any changes made
> upstream in Bitbucket.
> Note: changes made in GitLab will be overwritten by any changes made
> upstream in Bitbucket.
Create a file `build_status` and insert the script below and run
`chmod +x build_status` in your terminal to make the script executable.
Create a file `build_status` and insert the script below and run
`chmod +x build_status` in your terminal to make the script executable.
```bash
#!/usr/bin/env bash
```bash
#!/usr/bin/env bash
# Push GitLab CI/CD build status to Bitbucket Cloud
# Push GitLab CI/CD build status to Bitbucket Cloud
if [ -z "$BITBUCKET_ACCESS_TOKEN" ]; then
echo "ERROR: BITBUCKET_ACCESS_TOKEN is not set"
exit 1
fi
if [ -z "$BITBUCKET_USERNAME" ]; then
echo "ERROR: BITBUCKET_USERNAME is not set"
exit 1
fi
if [ -z "$BITBUCKET_NAMESPACE" ]; then
echo "Setting BITBUCKET_NAMESPACE to $CI_PROJECT_NAMESPACE"
BITBUCKET_NAMESPACE=$CI_PROJECT_NAMESPACE
fi
if [ -z "$BITBUCKET_REPOSITORY" ]; then
echo "Setting BITBUCKET_REPOSITORY to $CI_PROJECT_NAME"
BITBUCKET_REPOSITORY=$CI_PROJECT_NAME
fi
if [ -z "$BITBUCKET_ACCESS_TOKEN" ]; then
echo "ERROR: BITBUCKET_ACCESS_TOKEN is not set"
exit 1
fi
if [ -z "$BITBUCKET_USERNAME" ]; then
echo "ERROR: BITBUCKET_USERNAME is not set"
exit 1
fi
if [ -z "$BITBUCKET_NAMESPACE" ]; then
echo "Setting BITBUCKET_NAMESPACE to $CI_PROJECT_NAMESPACE"
BITBUCKET_NAMESPACE=$CI_PROJECT_NAMESPACE
fi
if [ -z "$BITBUCKET_REPOSITORY" ]; then
echo "Setting BITBUCKET_REPOSITORY to $CI_PROJECT_NAME"
BITBUCKET_REPOSITORY=$CI_PROJECT_NAME
fi
BITBUCKET_API_ROOT="https://api.bitbucket.org/2.0"
BITBUCKET_STATUS_API="$BITBUCKET_API_ROOT/repositories/$BITBUCKET_NAMESPACE/$BITBUCKET_REPOSITORY/commit/$CI_COMMIT_SHA/statuses/build"
BITBUCKET_KEY="ci/gitlab-ci/$CI_JOB_NAME"
BITBUCKET_API_ROOT="https://api.bitbucket.org/2.0"
BITBUCKET_STATUS_API="$BITBUCKET_API_ROOT/repositories/$BITBUCKET_NAMESPACE/$BITBUCKET_REPOSITORY/commit/$CI_COMMIT_SHA/statuses/build"
BITBUCKET_KEY="ci/gitlab-ci/$CI_JOB_NAME"
case "$BUILD_STATUS" in
running)
BITBUCKET_STATE="INPROGRESS"
BITBUCKET_DESCRIPTION="The build is running!"
;;
passed)
BITBUCKET_STATE="SUCCESSFUL"
BITBUCKET_DESCRIPTION="The build passed!"
;;
failed)
BITBUCKET_STATE="FAILED"
BITBUCKET_DESCRIPTION="The build failed."
;;
esac
case "$BUILD_STATUS" in
running)
BITBUCKET_STATE="INPROGRESS"
BITBUCKET_DESCRIPTION="The build is running!"
;;
passed)
BITBUCKET_STATE="SUCCESSFUL"
BITBUCKET_DESCRIPTION="The build passed!"
;;
failed)
BITBUCKET_STATE="FAILED"
BITBUCKET_DESCRIPTION="The build failed."
;;
esac
echo "Pushing status to $BITBUCKET_STATUS_API..."
curl --request POST $BITBUCKET_STATUS_API \
--user $BITBUCKET_USERNAME:$BITBUCKET_ACCESS_TOKEN \
--header "Content-Type:application/json" \
--silent \
--data "{ \"state\": \"$BITBUCKET_STATE\", \"key\": \"$BITBUCKET_KEY\", \"description\":
\"$BITBUCKET_DESCRIPTION\",\"url\": \"$CI_PROJECT_URL/-/jobs/$CI_JOB_ID\" }"
```
echo "Pushing status to $BITBUCKET_STATUS_API..."
curl --request POST $BITBUCKET_STATUS_API \
--user $BITBUCKET_USERNAME:$BITBUCKET_ACCESS_TOKEN \
--header "Content-Type:application/json" \
--silent \
--data "{ \"state\": \"$BITBUCKET_STATE\", \"key\": \"$BITBUCKET_KEY\", \"description\":
\"$BITBUCKET_DESCRIPTION\",\"url\": \"$CI_PROJECT_URL/-/jobs/$CI_JOB_ID\" }"
```
1. Still in Bitbucket, create a `.gitlab-ci.yml` file to use the script to push
pipeline success and failures to Bitbucket.
```yaml
stages:
- test
- ci_status
```yaml
stages:
- test
- ci_status
unit-tests:
script:
- echo "Success. Add your tests!"
unit-tests:
script:
- echo "Success. Add your tests!"
success:
stage: ci_status
before_script:
- ""
after_script:
- ""
script:
- BUILD_STATUS=passed BUILD_KEY=push ./build_status
when: on_success
success:
stage: ci_status
before_script:
- ""
after_script:
- ""
script:
- BUILD_STATUS=passed BUILD_KEY=push ./build_status
when: on_success
failure:
stage: ci_status
before_script:
- ""
after_script:
- ""
script:
- BUILD_STATUS=failed BUILD_KEY=push ./build_status
when: on_failure
```
failure:
stage: ci_status
before_script:
- ""
after_script:
- ""
script:
- BUILD_STATUS=failed BUILD_KEY=push ./build_status
when: on_failure
```
GitLab is now configured to mirror changes from Bitbucket, run CI/CD pipelines
configured in `.gitlab-ci.yml` and push the status to Bitbucket.

320
doc/ci/docker/using_docker_build.md
View file

@ -48,42 +48,42 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user.
1. During GitLab Runner installation select `shell` as method of executing job scripts or use command:
```bash
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor shell \
--description "My Runner"
```
```bash
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor shell \
--description "My Runner"
```
1. Install Docker Engine on server.
For more information how to install Docker Engine on different systems
checkout the [Supported installations](https://docs.docker.com/engine/installation/).
For more information how to install Docker Engine on different systems
checkout the [Supported installations](https://docs.docker.com/engine/installation/).
1. Add `gitlab-runner` user to `docker` group:
```bash
sudo usermod -aG docker gitlab-runner
```
```bash
sudo usermod -aG docker gitlab-runner
```
1. Verify that `gitlab-runner` has access to Docker:
```bash
sudo -u gitlab-runner -H docker info
```
```bash
sudo -u gitlab-runner -H docker info
```
You can now verify that everything works by adding `docker info` to `.gitlab-ci.yml`:
You can now verify that everything works by adding `docker info` to `.gitlab-ci.yml`:
```yaml
before_script:
- docker info
```yaml
before_script:
- docker info
build_image:
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
build_image:
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
1. You can now use `docker` command (and **install** `docker-compose` if needed).
@ -107,83 +107,83 @@ In order to do that, follow the steps:
1. Register GitLab Runner from the command line to use `docker` and `privileged`
mode:
```bash
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor docker \
--description "My Docker Runner" \
--docker-image "docker:stable" \
--docker-privileged
```
```bash
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor docker \
--description "My Docker Runner" \
--docker-image "docker:stable" \
--docker-privileged
```
The above command will register a new Runner to use the special
`docker:stable` image which is provided by Docker. **Notice that it's using
the `privileged` mode to start the build and service containers.** If you
want to use [docker-in-docker] mode, you always have to use `privileged = true`
in your Docker containers.
The above command will register a new Runner to use the special
`docker:stable` image which is provided by Docker. **Notice that it's using
the `privileged` mode to start the build and service containers.** If you
want to use [docker-in-docker] mode, you always have to use `privileged = true`
in your Docker containers.
DANGER: **Danger:**
By enabling `--docker-privileged`, you are effectively disabling all of
the security mechanisms of containers and exposing your host to privilege
escalation which can lead to container breakout. For more information, check
out the official Docker documentation on
[Runtime privilege and Linux capabilities][docker-cap].
DANGER: **Danger:**
By enabling `--docker-privileged`, you are effectively disabling all of
the security mechanisms of containers and exposing your host to privilege
escalation which can lead to container breakout. For more information, check
out the official Docker documentation on
[Runtime privilege and Linux capabilities][docker-cap].
The above command will create a `config.toml` entry similar to this:
The above command will create a `config.toml` entry similar to this:
```toml
[[runners]]
url = "https://gitlab.com/"
token = TOKEN
executor = "docker"
[runners.docker]
tls_verify = false
image = "docker:stable"
privileged = true
disable_cache = false
volumes = ["/cache"]
[runners.cache]
Insecure = false
```
```toml
[[runners]]
url = "https://gitlab.com/"
token = TOKEN
executor = "docker"
[runners.docker]
tls_verify = false
image = "docker:stable"
privileged = true
disable_cache = false
volumes = ["/cache"]
[runners.cache]
Insecure = false
```
1. You can now use `docker` in the build script (note the inclusion of the
`docker:dind` service):
```yaml
image: docker:stable
```yaml
image: docker:stable
variables:
# When using dind service we need to instruct docker, to talk with the
# daemon started inside of the service. The daemon is available with
# a network connection instead of the default /var/run/docker.sock socket.
#
# The 'docker' hostname is the alias of the service container as described at
# https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services
#
# Note that if you're using the Kubernetes executor, the variable should be set to
# tcp://localhost:2375/ because of how the Kubernetes executor connects services
# to the job container
# DOCKER_HOST: tcp://localhost:2375/
#
# For non-Kubernetes executors, we use tcp://docker:2375/
DOCKER_HOST: tcp://docker:2375/
# When using dind, it's wise to use the overlayfs driver for
# improved performance.
DOCKER_DRIVER: overlay2
variables:
# When using dind service we need to instruct docker, to talk with the
# daemon started inside of the service. The daemon is available with
# a network connection instead of the default /var/run/docker.sock socket.
#
# The 'docker' hostname is the alias of the service container as described at
# https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services
#
# Note that if you're using the Kubernetes executor, the variable should be set to
# tcp://localhost:2375/ because of how the Kubernetes executor connects services
# to the job container
# DOCKER_HOST: tcp://localhost:2375/
#
# For non-Kubernetes executors, we use tcp://docker:2375/
DOCKER_HOST: tcp://docker:2375/
# When using dind, it's wise to use the overlayfs driver for
# improved performance.
DOCKER_DRIVER: overlay2
services:
- docker:dind
services:
- docker:dind
before_script:
- docker info
before_script:
- docker info
build:
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
build:
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
Docker-in-Docker works well, and is the recommended configuration, but it is
not without its own challenges:
@ -202,14 +202,14 @@ not without its own challenges:
and use it as your mount point (for a more thorough explanation, check [issue
#41227](https://gitlab.com/gitlab-org/gitlab-ce/issues/41227)):
```yaml
variables:
MOUNT_POINT: /builds/$CI_PROJECT_PATH/mnt
```yaml
variables:
MOUNT_POINT: /builds/$CI_PROJECT_PATH/mnt
script:
- mkdir -p "$MOUNT_POINT"
- docker run -v "$MOUNT_POINT:/mnt" my-docker-image
```
script:
- mkdir -p "$MOUNT_POINT"
- docker run -v "$MOUNT_POINT:/mnt" my-docker-image
```
An example project using this approach can be found here: <https://gitlab.com/gitlab-examples/docker>.
@ -230,54 +230,54 @@ In order to do that, follow the steps:
1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`:
```bash
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor docker \
--description "My Docker Runner" \
--docker-image "docker:stable" \
--docker-volumes /var/run/docker.sock:/var/run/docker.sock
```
```bash
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor docker \
--description "My Docker Runner" \
--docker-image "docker:stable" \
--docker-volumes /var/run/docker.sock:/var/run/docker.sock
```
The above command will register a new Runner to use the special
`docker:stable` image which is provided by Docker. **Notice that it's using
the Docker daemon of the Runner itself, and any containers spawned by docker
commands will be siblings of the Runner rather than children of the runner.**
This may have complications and limitations that are unsuitable for your workflow.
The above command will register a new Runner to use the special
`docker:stable` image which is provided by Docker. **Notice that it's using
the Docker daemon of the Runner itself, and any containers spawned by docker
commands will be siblings of the Runner rather than children of the runner.**
This may have complications and limitations that are unsuitable for your workflow.
The above command will create a `config.toml` entry similar to this:
The above command will create a `config.toml` entry similar to this:
```toml
[[runners]]
url = "https://gitlab.com/"
token = REGISTRATION_TOKEN
executor = "docker"
[runners.docker]
tls_verify = false
image = "docker:stable"
privileged = false
disable_cache = false
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
[runners.cache]
Insecure = false
```
```toml
[[runners]]
url = "https://gitlab.com/"
token = REGISTRATION_TOKEN
executor = "docker"
[runners.docker]
tls_verify = false
image = "docker:stable"
privileged = false
disable_cache = false
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
[runners.cache]
Insecure = false
```
1. You can now use `docker` in the build script (note that you don't need to
include the `docker:dind` service as when using the Docker in Docker executor):
```yaml
image: docker:stable
```yaml
image: docker:stable
before_script:
- docker info
before_script:
- docker info
build:
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
build:
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
While the above method avoids using Docker in privileged mode, you should be
aware of the following implications:
@ -293,9 +293,9 @@ aware of the following implications:
work as expected since volume mounting is done in the context of the host
machine, not the build container. For example:
```sh
docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests
```
```sh
docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests
```
## Making docker-in-docker builds faster with Docker layer caching
@ -366,23 +366,23 @@ which can be avoided if a different driver is used, for example `overlay2`.
1. Make sure a recent kernel is used, preferably `>= 4.2`.
1. Check whether the `overlay` module is loaded:
```sh
sudo lsmod | grep overlay
```
```sh
sudo lsmod | grep overlay
```
If you see no result, then it isn't loaded. To load it use:
If you see no result, then it isn't loaded. To load it use:
```sh
sudo modprobe overlay
```
```sh
sudo modprobe overlay
```
If everything went fine, you need to make sure module is loaded on reboot.
On Ubuntu systems, this is done by editing `/etc/modules`. Just add the
following line into it:
If everything went fine, you need to make sure module is loaded on reboot.
On Ubuntu systems, this is done by editing `/etc/modules`. Just add the
following line into it:
```text
overlay
```
```text
overlay
```
### Use driver per project
@ -450,9 +450,9 @@ For all projects, mostly suitable for public ones:
your Docker images and has read/write access to the Registry. This is ephemeral,
so it's only valid for one job. You can use the following example as-is:
```sh
docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
```
```sh
docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
```
For private and internal projects:
@ -465,9 +465,9 @@ For private and internal projects:
Replace the `<username>` and `<access_token>` in the following example:
```sh
docker login -u <username> -p <access_token> $CI_REGISTRY
```
```sh
docker login -u <username> -p <access_token> $CI_REGISTRY
```
- **Using the GitLab Deploy Token**: You can create and use a
[special deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token)
@ -475,9 +475,9 @@ For private and internal projects:
Once created, you can use the special environment variables, and GitLab CI/CD
will fill them in for you. You can use the following example as-is:
```sh
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
```sh
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
### Container Registry examples

131
doc/ci/docker/using_docker_images.md
View file

@ -305,25 +305,25 @@ For example, the following two definitions are equal:
1. Using a string as an option to `image` and `services`:
```yaml
image: "registry.example.com/my/image:latest"
```yaml
image: "registry.example.com/my/image:latest"
services:
- postgresql:9.4
- redis:latest
```
services:
- postgresql:9.4
- redis:latest
```
1. Using a map as an option to `image` and `services`. The use of `image:name` is
required:
```yaml
image:
name: "registry.example.com/my/image:latest"
```yaml
image:
name: "registry.example.com/my/image:latest"
services:
- name: postgresql:9.4
- name: redis:latest
```
services:
- name: postgresql:9.4
- name: redis:latest
```
### Available settings for `image`
@ -526,6 +526,7 @@ it's provided as an environment variable. This is because GitLab Runnner uses **
runtime.
### Using statically-defined credentials
There are two approaches that you can take in order to access a
private registry. Both require setting the environment variable
`DOCKER_AUTH_CONFIG` with appropriate authentication info.
@ -555,18 +556,18 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`:
- **First way -** Do a `docker login` on your local machine:
```bash
docker login registry.example.com:5000 --username my_username --password my_password
```
```bash
docker login registry.example.com:5000 --username my_username --password my_password
```
Then copy the content of `~/.docker/config.json`.
Then copy the content of `~/.docker/config.json`.
If you don't need access to the registry from your computer, you
can do a `docker logout`:
If you don't need access to the registry from your computer, you
can do a `docker logout`:
```bash
docker logout registry.example.com:5000
```
```bash
docker logout registry.example.com:5000
```
- **Second way -** In some setups, it's possible that Docker client
will use the available system keystore to store the result of `docker
@ -575,12 +576,12 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`:
`${username}:${password}` manually. Open a terminal and execute the
following command:
```bash
echo -n "my_username:my_password" | base64
```bash
echo -n "my_username:my_password" | base64
# Example output to copy
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
```
# Example output to copy
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
```
#### Configuring a job
@ -590,25 +591,25 @@ follow these steps:
1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the
Docker configuration file as the value:
```json
{
"auths": {
"registry.example.com:5000": {
"auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
}
}
}
```
```json
{
"auths": {
"registry.example.com:5000": {
"auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
}
}
}
```
1. You can now use any private image from `registry.example.com:5000` defined in
`image` and/or `services` in your `.gitlab-ci.yml` file:
```yaml
image: registry.example.com:5000/namespace/image:tag
```
```yaml
image: registry.example.com:5000/namespace/image:tag
```
In the example above, GitLab Runner will look at `registry.example.com:5000` for the
image `namespace/image:tag`.
In the example above, GitLab Runner will look at `registry.example.com:5000` for the
image `namespace/image:tag`.
You can add configuration for as many registries as you want, adding more
registries to the `"auths"` hash as described above.
@ -637,10 +638,10 @@ To add `DOCKER_AUTH_CONFIG` to a Runner:
1. Modify the Runner's `config.toml` file as follows:
```toml
[[runners]]
environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"]
```
```toml
[[runners]]
environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"]
```
1. Restart the Runner service.
@ -662,16 +663,17 @@ To configure credentials store, follow these steps:
Make sure helper program is available in GitLab Runner `$PATH`.
1. Make GitLab Runner use it. There are two ways to accomplish this. Either:
- Create a
[variable](../variables/README.md#gitlab-cicd-environment-variables)
`DOCKER_AUTH_CONFIG` with the content of the
Docker configuration file as the value:
Docker configuration file as the value:
```json
{
"credsStore": "osxkeychain"
}
```
```json
{
"credsStore": "osxkeychain"
}
```
- Or, if you are running self-hosted Runners, add the above JSON to
`${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner will read this config file
@ -693,17 +695,18 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th
1. Make sure `docker-credential-ecr-login` is available in GitLab Runner's `$PATH`.
1. Make GitLab Runner use it. There are two ways to accomplish this. Either:
- Create a [variable](../variables/README.md#gitlab-cicd-environment-variables)
`DOCKER_AUTH_CONFIG` with the content of the
Docker configuration file as the value:
Docker configuration file as the value:
```json
{
"credHelpers": {
"aws_account_id.dkr.ecr.region.amazonaws.com": "ecr-login"
}
}
```
```json
{
"credHelpers": {
"aws_account_id.dkr.ecr.region.amazonaws.com": "ecr-login"
}
}
```
- Or, if you are running self-hosted Runners,
add the above JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`.
@ -713,12 +716,12 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th
1. You can now use any private image from `aws_account_id.dkr.ecr.region.amazonaws.com` defined in
`image` and/or `services` in your `.gitlab-ci.yml` file:
```yaml
image: aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest
```
```yaml
image: aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest
```
In the example above, GitLab Runner will look at `aws_account_id.dkr.ecr.region.amazonaws.com` for the
image `private/image:latest`.
In the example above, GitLab Runner will look at `aws_account_id.dkr.ecr.region.amazonaws.com` for the
image `private/image:latest`.
You can add configuration for as many registries as you want, adding more
registries to the `"credHelpers"` hash as described above.

70
doc/ci/examples/artifactory_and_gitlab/index.md
View file

@ -39,9 +39,10 @@ project:
1. Create a new project by selecting **Import project from ➔ Repo by URL**
1. Add the following URL:
```
https://gitlab.com/gitlab-examples/maven/simple-maven-dep.git
```
```
https://gitlab.com/gitlab-examples/maven/simple-maven-dep.git
```
1. Click **Create project**
This application is nothing more than a basic class with a stub for a JUnit based test suite.
@ -63,15 +64,15 @@ The application is ready to use, but you need some additional steps to deploy it
1. Copy the snippet in the `pom.xml` file for your project, just after the
`dependencies` section. The snippet should look like this:
```xml
<distributionManagement>
<repository>
<id>central</id>
<name>83d43b5afeb5-releases</name>
<url>${env.MAVEN_REPO_URL}/libs-release-local</url>
</repository>
</distributionManagement>
```
```xml
<distributionManagement>
<repository>
<id>central</id>
<name>83d43b5afeb5-releases</name>
<url>${env.MAVEN_REPO_URL}/libs-release-local</url>
</repository>
</distributionManagement>
```
Another step you need to do before you can deploy the dependency to Artifactory
is to configure the authentication data. It is a simple task, but Maven requires
@ -86,18 +87,18 @@ parameter in `.gitlab-ci.yml` to use the custom location instead of the default
1. Create a file called `settings.xml` in the `.m2` folder
1. Copy the following content into a `settings.xml` file:
```xml
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<servers>
<server>
<id>central</id>
<username>${env.MAVEN_REPO_USER}</username>
<password>${env.MAVEN_REPO_PASS}</password>
</server>
</servers>
</settings>
```
```xml
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<servers>
<server>
<id>central</id>
<username>${env.MAVEN_REPO_USER}</username>
<password>${env.MAVEN_REPO_PASS}</password>
</server>
</servers>
</settings>
```
Username and password will be replaced by the correct values using variables.
@ -187,9 +188,10 @@ We'll use again a Maven app that can be cloned from our example project:
1. Create a new project by selecting **Import project from ➔ Repo by URL**
1. Add the following URL:
```
https://gitlab.com/gitlab-examples/maven/simple-maven-app.git
```
```
https://gitlab.com/gitlab-examples/maven/simple-maven-app.git
```
1. Click **Create project**
This one is a simple app as well. If you look at the `src/main/java/com/example/app/App.java`
@ -204,13 +206,13 @@ Since Maven doesn't know how to resolve the dependency, you need to modify the c
1. Copy the snippet in the `dependencies` section of the `pom.xml` file.
The snippet should look like this:
```xml
<dependency>
<groupId>com.example.dep</groupId>
<artifactId>simple-maven-dep</artifactId>
<version>1.0</version>
</dependency>
```
```xml
<dependency>
<groupId>com.example.dep</groupId>
<artifactId>simple-maven-dep</artifactId>
<version>1.0</version>
</dependency>
```
### Configure the Artifactory repository location

107
doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md
View file

@ -188,28 +188,27 @@ when running our Phoenix in our `localhost`.
- Open `hello_gitlab_ci/config/test.exs` on your favorite code editor
- Go to **Configure your database** session and edit the block to include `System.get_env`:
```elixir
# Configure your database
config :hello_gitlab_ci, HelloGitlabCi.Repo,
adapter: Ecto.Adapters.Postgres,
username: System.get_env("POSTGRES_USER") || "postgres",
password: System.get_env("POSTGRES_PASSWORD") || "postgres",
database: System.get_env("POSTGRES_DB") || "hello_gitlab_ci_test",
hostname: System.get_env("POSTGRES_HOST") || "localhost",
pool: Ecto.Adapters.SQL.Sandbox
```
```elixir
# Configure your database
config :hello_gitlab_ci, HelloGitlabCi.Repo,
adapter: Ecto.Adapters.Postgres,
username: System.get_env("POSTGRES_USER") || "postgres",
password: System.get_env("POSTGRES_PASSWORD") || "postgres",
database: System.get_env("POSTGRES_DB") || "hello_gitlab_ci_test",
hostname: System.get_env("POSTGRES_HOST") || "localhost",
pool: Ecto.Adapters.SQL.Sandbox
```
We'll need these system variables later on.
We'll need these system variables later on.
- Create an empty file named `.gitkeep` into `hello_gitlab_ci/priv/repo/migrations`
As our project is still fresh, we don't have any data on our database, so, the `migrations`
directory will be empty.
Without `.gitkeep`, git will not upload this empty directory and we'll got an error when running our
test on GitLab.
As our project is still fresh, we don't have any data on our database, so, the `migrations`
directory will be empty.
Without `.gitkeep`, git will not upload this empty directory and we'll got an error when running our
test on GitLab.
> **Note:**
If we add a folder via the GitLab UI, GitLab itself will add the `.gitkeep` to that new dir.
> **Note:** If we add a folder via the GitLab UI, GitLab itself will add the `.gitkeep` to that new dir.
Now, let's run a local test and see if everything we did didn't break anything.
@ -248,64 +247,64 @@ project.
- The fastest and easiest way to do this, is to click on **Set up CI** on project's main page:
![Set up CI](img/setup-ci.png)
![Set up CI](img/setup-ci.png)
- On next screen, we can select a template ready to go. Click on **Apply a GitLab CI/CD Yaml
template** and select **Elixir**:
![Select template](img/select-template.png)
![Select template](img/select-template.png)
This template file tells GitLab CI/CD about what we wish to do every time a new commit is made.
However, we have to adapt it to run a Phoenix app.
This template file tells GitLab CI/CD about what we wish to do every time a new commit is made.
However, we have to adapt it to run a Phoenix app.
- The first line tells GitLab what Docker image will be used.
Remember when we learn about Runners, the isolated virtual machine where GitLab CI/CD build and test
our application? This virtual machine must have all dependencies to run our application. This is
where a Docker image is needed. The correct image will provide the entire system for us.
Remember when we learn about Runners, the isolated virtual machine where GitLab CI/CD build and test
our application? This virtual machine must have all dependencies to run our application. This is
where a Docker image is needed. The correct image will provide the entire system for us.
As a suggestion, you can use [trenpixster's elixir image][docker-image], which already has all
dependencies for Phoenix installed, such as Elixir, Erlang, NodeJS and PostgreSQL:
As a suggestion, you can use [trenpixster's elixir image][docker-image], which already has all
dependencies for Phoenix installed, such as Elixir, Erlang, NodeJS and PostgreSQL:
```yml
image: trenpixster/elixir:latest
```
```yml
image: trenpixster/elixir:latest
```
- At `services` session, we'll only use `postgres`, so we'll delete `mysql` and `redis` lines:
```yml
services:
- postgres:latest
```
```yml
services:
- postgres:latest
```
- Now, we'll create a new entry called `variables`, before `before_script` session:
```yml
variables:
POSTGRES_DB: hello_gitlab_ci_test
POSTGRES_HOST: postgres
POSTGRES_USER: postgres
POSTGRES_PASSWORD: "postgres"
MIX_ENV: "test"
```
```yml
variables:
POSTGRES_DB: hello_gitlab_ci_test
POSTGRES_HOST: postgres
POSTGRES_USER: postgres
POSTGRES_PASSWORD: "postgres"
MIX_ENV: "test"
```
Here, we are setting up the values for GitLab CI/CD authenticate into PostgreSQL, as we did on
`config/test.exs` earlier.
Here, we are setting up the values for GitLab CI/CD authenticate into PostgreSQL, as we did on
`config/test.exs` earlier.
- In `before_script` session, we'll add some commands to prepare everything to the test:
```yml
before_script:
- apt-get update && apt-get -y install postgresql-client
- mix local.hex --force
- mix deps.get --only test
- mix ecto.create
- mix ecto.migrate
```
```yml
before_script:
- apt-get update && apt-get -y install postgresql-client
- mix local.hex --force
- mix deps.get --only test
- mix ecto.create
- mix ecto.migrate
```
It's important to install `postgresql-client` to let GitLab CI/CD access PostgreSQL and create our
database with the login information provided earlier. More important is to respect the indentation,
to avoid syntax errors when running the build.
It's important to install `postgresql-client` to let GitLab CI/CD access PostgreSQL and create our
database with the login information provided earlier. More important is to respect the indentation,
to avoid syntax errors when running the build.
- And finally, we'll let `mix` session intact.

72
doc/ci/ssh_keys/README.md
View file

@ -57,44 +57,44 @@ to access it. This is where an SSH key pair comes in handy.
1. Modify your `.gitlab-ci.yml` with a `before_script` action. In the following
example, a Debian based image is assumed. Edit to your needs:
```yaml
before_script:
##
## Install ssh-agent if not already installed, it is required by Docker.
## (change apt-get to yum if you use an RPM-based image)
##
- 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
```yaml
before_script:
##
## Install ssh-agent if not already installed, it is required by Docker.
## (change apt-get to yum if you use an RPM-based image)
##
- 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
##
## Run ssh-agent (inside the build environment)
##
- eval $(ssh-agent -s)
##
## Run ssh-agent (inside the build environment)
##
- eval $(ssh-agent -s)
##
## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
## We're using tr to fix line endings which makes ed25519 keys work
## without extra base64 encoding.
## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
##
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
##
## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
## We're using tr to fix line endings which makes ed25519 keys work
## without extra base64 encoding.
## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
##
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
##
## Create the SSH directory and give it the right permissions
##
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
##
## Create the SSH directory and give it the right permissions
##
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
##
## Optionally, if you will be using any Git commands, set the user name and
## and email.
##
#- git config --global user.email "user@example.com"
#- git config --global user.name "User name"
```
##
## Optionally, if you will be using any Git commands, set the user name and
## and email.
##
#- git config --global user.email "user@example.com"
#- git config --global user.name "User name"
```
NOTE: **Note:**
The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally
or per-job.
NOTE: **Note:**
The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally
or per-job.
1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys).
@ -118,9 +118,9 @@ on, and use that key for all projects that are run on this machine.
1. Then from the terminal login as the `gitlab-runner` user:
```
sudo su - gitlab-runner
```
```
sudo su - gitlab-runner
```
1. Generate the SSH key pair as described in the instructions to
[generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair).

16
doc/ci/yaml/README.md
View file

@ -2468,20 +2468,20 @@ There are three possible values: `none`, `normal`, and `recursive`:
- `normal` means that only the top-level submodules will be included. It is
equivalent to:
```
git submodule sync
git submodule update --init
```
```
git submodule sync
git submodule update --init
```
- `recursive` means that all submodules (including submodules of submodules)
will be included. This feature needs Git v1.8.1 and later. When using a
GitLab Runner with an executor not based on Docker, make sure the Git version
meets that requirement. It is equivalent to:
```
git submodule sync --recursive
git submodule update --init --recursive
```
```
git submodule sync --recursive
git submodule update --init --recursive
```
Note that for this feature to work correctly, the submodules must be configured
(in `.gitmodules`) with either: