|
| 1 | +--- |
| 2 | +description: Access repositories on any Git server via SSH |
| 3 | +--- |
| 4 | + |
| 5 | +# Connect Any Git Server |
| 6 | + |
| 7 | +import Tabs from '@theme/Tabs'; |
| 8 | +import TabItem from '@theme/TabItem'; |
| 9 | +import Available from '@site/src/components/Available'; |
| 10 | +import VideoTutorial from '@site/src/components/VideoTutorial'; |
| 11 | +import Steps from '@site/src/components/Steps'; |
| 12 | + |
| 13 | +This page explains how to add a project hosted on a private Git server. |
| 14 | + |
| 15 | +## Overview |
| 16 | + |
| 17 | +Semaphore can work with repositories hosted on any privately-run [Git server](https://git-scm.com/book/en/v2/Git-on-the-Server-Getting-Git-on-a-Server) via SSH. |
| 18 | + |
| 19 | +Before you start, ensure you have SSH access to the machine running the Git service. Then, take note of the following parameters: |
| 20 | + |
| 21 | +- public IP or domain name of your Git server, e.g. `my-git-server.org`) |
| 22 | +- user running the Git service, e.g. `git` |
| 23 | +- home directory for the user running the git service, e.g. `/home/git` |
| 24 | +- directory containing the repositories, e.g. `/srv/git` |
| 25 | + |
| 26 | +## How to create a bare repository {#bare} |
| 27 | + |
| 28 | +This section provides a guide on creating a new repository to practice to anyone new to the world of private Git servers. You can skip this section if you're familiar with managing Git servers. |
| 29 | + |
| 30 | +To create a new repository: |
| 31 | + |
| 32 | +<Steps> |
| 33 | + |
| 34 | +1. Connect to the server running the Git service, e.g. `ssh [email protected]` |
| 35 | + |
| 36 | +2. Change to the directory where the repositories are hosted, e.g. `cd /srv/git` |
| 37 | + |
| 38 | +3. Create a new bare repository, e.g. `git init --bare my-repo.git` |
| 39 | + |
| 40 | +4. On a different terminal, clone the remote repository to your local machine, e.g. `git clone ssh://[email protected]/srv/git/my-repo.git` |
| 41 | + |
| 42 | +5. Once cloned, ensure the repository has at least one commit (so it is not empty), e.g. |
| 43 | + |
| 44 | + ```shell |
| 45 | + cd my-repo |
| 46 | + echo "# This is a test" > README.md |
| 47 | + git add README.md |
| 48 | + git commit -m initial commit |
| 49 | + git push origin main |
| 50 | + ``` |
| 51 | + |
| 52 | +</Steps> |
| 53 | + |
| 54 | +## How to create a project {#create} |
| 55 | + |
| 56 | +To connect with this method, press the **Create new** button. |
| 57 | + |
| 58 | + |
| 59 | + |
| 60 | +<Steps> |
| 61 | + |
| 62 | +1. Select the **Generic Git** |
| 63 | + |
| 64 | + <details> |
| 65 | + <summary>Show me</summary> |
| 66 | + <div> |
| 67 | +  |
| 68 | + </div> |
| 69 | + </details> |
| 70 | + |
| 71 | +2. Type the SSH URL used to clone the repository, e.g. `ssh://[email protected]/srv/git/my-repo.git` |
| 72 | + |
| 73 | +3. Optionally, change the name of the project |
| 74 | + |
| 75 | + <details> |
| 76 | + <summary>Show me</summary> |
| 77 | + <div> |
| 78 | +  |
| 79 | + </div> |
| 80 | + </details> |
| 81 | + |
| 82 | +4. Copy the public SSH key shown on screen |
| 83 | + |
| 84 | + |
| 85 | + <details> |
| 86 | + <summary>Show me</summary> |
| 87 | + <div> |
| 88 | +  |
| 89 | + </div> |
| 90 | + </details> |
| 91 | + |
| 92 | +5. SSH into the Git server add the SSH key copied in the previous step to `$HOME/.ssh/authorized_keys` (relative to the user that runs the Git service) and press **Continue** |
| 93 | + |
| 94 | +6. Back in Sempahore, press the **Generate Script** button |
| 95 | + |
| 96 | + <details> |
| 97 | + <summary>Show me</summary> |
| 98 | + <div> |
| 99 | +  |
| 100 | + </div> |
| 101 | + </details> |
| 102 | + |
| 103 | +7. In the Git server, go into the directory containing the bare repository (e.g. `/srv/git/my-repo.git`) |
| 104 | + |
| 105 | +8. Create the [post-receive](https://git-scm.com/docs/githooks#post-receive) script in the `hooks` directory, pay attention to: |
| 106 | + |
| 107 | + - Filename: `post-receive` |
| 108 | + - Contents: the script copied in Step 6 |
| 109 | + - Owner: check that the script is owned by the same user running the Git service, e.g. `chown git:git post-receive` |
| 110 | + - Permission to execute: `chmod a+x post-receive` |
| 111 | + - Prerequisite packages: [curl](https://curl.se/) |
| 112 | + |
| 113 | +9. Semaphore will wait for the post-receive hook to be executed. To do that, commit and push a new/modified file into the repository. |
| 114 | + |
| 115 | +10. Back in Semaphore, once the Git hook is executed, press **Configure workflow** |
| 116 | + |
| 117 | +11. Select the default [agent](./pipelines#agents) for this project and press **Continue** |
| 118 | + |
| 119 | + <details> |
| 120 | + <summary>Show me</summary> |
| 121 | + <div> |
| 122 | +  |
| 123 | + </div> |
| 124 | + </details> |
| 125 | + |
| 126 | +12. Select a starter workflow. You may also **Customize** or **Design from scratch** |
| 127 | + |
| 128 | + |
| 129 | + <details> |
| 130 | + <summary>Show me</summary> |
| 131 | + <div> |
| 132 | +  |
| 133 | + </div> |
| 134 | + </details> |
| 135 | + |
| 136 | +</Steps> |
| 137 | + |
| 138 | +## Troubleshooting guide |
| 139 | + |
| 140 | +If your repositories aren't showing in Semaphore or changes are not triggering new workflows, check the connection between Semaphore and your Git server. |
| 141 | +
|
| 142 | +### Verify deploy key and webhook {#deploy-key} |
| 143 | +
|
| 144 | +<Steps> |
| 145 | +
|
| 146 | +1. Open your project |
| 147 | +
|
| 148 | +2. Go to the **Settings**, then **Repository** |
| 149 | +
|
| 150 | +  |
| 151 | +
|
| 152 | +3. Check the status of **Deploy Key** and **Webhook**. Press **Regenerate** if any of parameters are marked with error: |
| 153 | +
|
| 154 | + - If regenerating a deployment key, you must update the `$HOME/.ssh/authorized_keys` (see Step 4 of [How to create a project](#create)) |
| 155 | + - If regenerating the webhook, update the `endpoint` value in the `post-receive` hook (see Step 8 of [How to create a project](#create)) |
| 156 | +
|
| 157 | +
|
| 158 | +</Steps> |
| 159 | +
|
| 160 | +### Reconnecting moved or renamed projects {#reconnect} |
| 161 | +
|
| 162 | +There are several actions that can break the connection between the Git server and Semaphore. For example: |
| 163 | +
|
| 164 | +- moving the repository to a different location |
| 165 | +- renaming the repository |
| 166 | +
|
| 167 | +When this happens, you must update the URL of the repository in Semaphore. To do this: |
| 168 | +
|
| 169 | +<Steps> |
| 170 | +
|
| 171 | +1. Open your [project settings](./projects#settings) |
| 172 | +2. Type the new repository URL |
| 173 | +3. Press **Change** |
| 174 | +  |
| 175 | +
|
| 176 | +</Steps> |
| 177 | +
|
| 178 | +After changing the URL, double-check the status of the [deploy key](#deploy-key) and webhook. |
| 179 | +
|
| 180 | +### File semaphore.yml is not available |
| 181 | +
|
| 182 | +You might see the following error message when trying to run workflows on Semaphore: |
| 183 | +
|
| 184 | +``` yaml |
| 185 | +semaphore.yml ERROR: |
| 186 | +Error: {"File '.semaphore/semaphore.yml' is not available", "Not Found"} |
| 187 | +``` |
| 188 | +
|
| 189 | +This means that Semaphore can't fetch the `.semaphore/semaphore.yml` file from the repository. There are two reasons why this might happen: |
| 190 | + |
| 191 | +1. **The file doesn't exist on your repository**: double check to make sure that the Semaphore YAML file actually exists |
| 192 | +2. **Repository is disconnected from Semaphore**: follow the steps [previously described](#reconnect) |
| 193 | +
|
| 194 | +## See also |
| 195 | +
|
| 196 | +- [Getting Started Guide](../getting-started/guided-tour) |
| 197 | +- [How to connect with GitHub App](./connect-github) |
| 198 | +- [How to connect with BitBucket](./connect-bitbucket) |
| 199 | +- [How to connect with GitLab](./connect-gitlab) |
| 200 | +
|
0 commit comments