Clean up CI ssh keys docs [ci skip]
This commit is contained in:
parent
9b8babb601
commit
d13d43aca9
|
@ -1,114 +1,109 @@
|
|||
# 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
|
||||
### How it works
|
||||
|
||||
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]-----+
|
||||
```
|
||||
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.
|
||||
|
||||
2. Create a new **Secure Variable** in your project settings on GitLab and name it: `SSH_PRIVATE_KEY`.
|
||||
## SSH keys when using the Docker executor
|
||||
|
||||
3. Copy the content of `my_key` and paste it as a **Value** of **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).
|
||||
|
||||
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 (in build environment)
|
||||
- eval $(ssh-agent -s)
|
||||
# Run ssh-agent (inside the build environment)
|
||||
- eval $(ssh-agent -s)
|
||||
|
||||
# add ssh key stored in SSH_PRIVATE_KEY variable to the agent store
|
||||
- ssh-add <(echo "$SSH_PRIVATE_KEY")
|
||||
# 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, 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`
|
||||
# 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`
|
||||
```
|
||||
|
||||
5. Add the public key from `my_key.pub` to services that you want to have an access from build.
|
||||
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).
|
||||
|
||||
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.
|
||||
That's it! You can now have access to private servers or repositories in your
|
||||
build environment.
|
||||
|
||||
## SSH keys when using Shell executor
|
||||
If use `shell`, not `docker` it can be easier to have the SSH key.
|
||||
## SSH keys when using the Shell executor
|
||||
|
||||
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.
|
||||
If you are using the Shell executor and not Docker, it is easier to set up an
|
||||
SSH key.
|
||||
|
||||
1. First, login to server that runs your builds.
|
||||
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.
|
||||
|
||||
First, you need to login to the server that runs your builds.
|
||||
|
||||
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).
|
||||
|
||||
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/
|
||||
|
|
Loading…
Reference in New Issue