Skip to content

G
gitlab-ce
Commit d13d43ac authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Clean up CI ssh keys docs [ci skip]

parent 9b8babb6
Show whitespace changes
Inline Side-by-side
Showing with 81 additions and 86 deletions
doc/ci/ssh_keys/README.md
View file @ d13d43ac
# Using SSH keys
GitLab currently doesn't have built-in support for SSH keys in build environment.
GitLab currently doesn't have built-in support for managing SSH keys in a build
environment.
The SSH keys can be useful when:
1. You want to checkout internal submodules,
2. You want to download private packages using your package manager (ie. bundler),
3. You want to deploy your app (ex. to Heroku or own server),
4. You want to execute ssh commands from build environment on remote server,
5. You want to rsync files from your build to remote server.
If anyone of the above holds true, then you most likely need SSH key.
1. You want to checkout internal submodules
2. You want to download private packages using your package manager (eg. bundler)
3. You want to deploy your application to eg. Heroku or your own server
4. You want to execute SSH commands from the build server to the remote server
5. You want to rsync files from your build server to the remote server
There are two possibilities to add SSH keys to build environment.
If anything of the above rings a bell, then you most likely need an SSH key.
## Inject keys in your build environment
The most widely supported is to inject SSH key into your build environment by extending your .gitlab-ci.yml.
This is the universal solution which works with any type of executor (docker, shell, etc.).
## Inject keys in your build server
### How it works?
1. We create a new SSH private key with [ssh-keygen](http://linux.die.net/man/1/ssh-keygen).
2. We add the private key as the Secure Variable to project.
3. We run the [ssh-agent](http://linux.die.net/man/1/ssh-agent) during build to load the private key.
The most widely supported method is to inject an SSH key into your build
environment by extending your `.gitlab-ci.yml`.
The example [.gitlab-ci.yml](https://gitlab.com/gitlab-examples/ssh-private-key/blob/master/.gitlab-ci.yml) looks like this.
This is the universal solution which works with any type of executor
(docker, shell, etc.).
### Make it work?
1. First, go to terminal and generate a new SSH key:
```bash
$ ssh-keygen -t rsa -f my_key
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in my_key.
Your public key has been saved in my_key.pub.
The key fingerprint is:
SHA256:tBJEfyJUGTMNmPCiPg4UHywHs67MxlM2iEBAlI/W+TY fingeprint
The key's randomart image is:
+---[RSA 2048]----+
|=*. .o++*= |
|..= +o..o. |
|.+++o + + . |
|+o*=.. + + |
|o+.=. . S |
|*.o .E . |
|o*o . . |
|.o.. |
| . |
+----[SHA256]-----+
```
### How it works
1. Create a new SSH key pair with [ssh-keygen][]
2. Add the private key as a **Secret Variable** to the project
3. Run the [ssh-agent][] during build to load the private key.
## SSH keys when using the Docker executor
2. Create a new **Secure Variable** in your project settings on GitLab and name it: `SSH_PRIVATE_KEY`.
You will first need to create an SSH key pair. For more information, follow the
instructions to [generate an SSH key](../ssh/README.md).
3. Copy the content of `my_key` and paste it as a **Value** of **SSH_PRIVATE_KEY**.
Then, create a new **Secret Variable** in your project settings on GitLab
following **Settings > Variables**. As **Key** add the name `SSH_PRIVATE_KEY`
and in the **Value** field paste the content of your _private_ key that you
created earlier.
Next you need to modify your `.gitlab-ci.yml` with a `before_script` action.
Add it to the top:
4. Next you need to modify your `.gitlab-ci.yml` and at the top of the file add:
```
before_script:
# install ssh-agent (it is required for Docker, change apt-get to yum if you use CentOS-based image)
- 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
# Install ssh-agent if not already installed, it is required by Docker.
# (change apt-get to yum if you use a CentOS-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)
# Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
- ssh-add <(echo "$SSH_PRIVATE_KEY")
# For Docker builds disable host key checking. Be aware that by adding that
# you are suspectible to man-in-the-middle attacks.
# WARNING: Use this only with the Docker executor, if you use it with shell
# you will overwrite your user's SSH config.
- mkdir -p ~/.ssh
- '[[ -f /.dockerinit ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config`
```
# run ssh-agent (in build environment)
- eval $(ssh-agent -s)
As a final step, add the _public_ key from the one you created earlier to the
services that you want to have an access to from within the build environment.
If you are accessing a private GitLab repository you need to add it as a
[deploy key](../ssh/README.md#deploy-keys).
# add ssh key stored in SSH_PRIVATE_KEY variable to the agent store
- ssh-add <(echo "$SSH_PRIVATE_KEY")
That's it! You can now have access to private servers or repositories in your
build environment.
# for Docker builds disable host key checking, by adding that you are suspectible to man-in-the-middle attack
- mkdir -p ~/.ssh
- '[[ -f /.dockerinit ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config`
```
## SSH keys when using the Shell executor
5. Add the public key from `my_key.pub` to services that you want to have an access from build.
If you are using the Shell executor and not Docker, it is easier to set up an
SSH key.
6. If your builds are run using `shell` executor, you may need to login to server and execute the `ssh <address-of-my-server>` to store the fingerprint of remote server.
You can generate the SSH key from the machine that GitLab Runner is installed
on, and use that key for all projects that are run on this machine.
## SSH keys when using Shell executor
If use `shell`, not `docker` it can be easier to have the SSH key.
First, you need to login to the server that runs your builds.
We can generate the SSH key for the machine that holds `gitlab-runner` and use that key for all projects that are run on this machine.
Then from the terminal login as the `gitlab-runner` user and generate the SSH
key pair as described in the [SSH keys documentation](../ssh/README.md).
1. First, login to server that runs your builds.
As a final step, add the _public_ key from the one you created earlier to the
services that you want to have an access to from within the build environment.
If you are accessing a private GitLab repository you need to add it as a
[deploy key](../ssh/README.md#deploy-keys).
Once done, try to login to the remote server in order to accept the fingerprint:
2. From terminal login as `gitlab-runner` user and generate the SSH private key:
```bash
$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ~/.ssh/id_rsa.
Your public key has been saved in ~/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:tBJEfyJUGTMNmPCiPg4UHywHs67MxlM2iEBAlI/W+TY fingeprint
The key's randomart image is:
+---[RSA 2048]----+
|=*. .o++*= |
|..= +o..o. |
|.+++o + + . |
|+o*=.. + + |
|o+.=. . S |
|*.o .E . |
|o*o . . |
|.o.. |
| . |
+----[SHA256]-----+
ssh <address-of-my-server>
```
3. Add the public key from `~/.ssh/id_rsa.pub` to services that you want to have an access from build.
For accessing repositories on GitLab.com, the `<address-of-my-server>` would be
`git@gitlab.com`.
4. Try to login for the first time and accept fingerprint:
```bash
ssh <address-of-my-server
```
## Example project
We have set up an [Example SSH Project][ssh-example-repo] for your convenience
that runs on [GitLab.com](https://gitlab.com) using our publicly available
[shared runners](../runners/README.md).
Want to hack on it? Simply fork it, commit and push your changes. Within a few
moments the changes will be picked by a public runner and the build will begin.
[ssh-keygen]: http://linux.die.net/man/1/ssh-keygen
[ssh-agent]: http://linux.die.net/man/1/ssh-agent
[ssh-example-repo]: https://gitlab.com/gitlab-examples/ssh-private-key/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7