Added Troubleshooting information for most used services.
This commit is contained in:
parent
00cb4a9714
commit
cf232411ae
|
@ -39,3 +39,34 @@ please see the [project_services directory][projects-code].
|
|||
[jenkins]: http://doc.gitlab.com/ee/integration/jenkins.html
|
||||
[Project Service]: ../project_services/project_services.md
|
||||
[projects-code]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/models/project_services
|
||||
|
||||
## SSL certificate errors
|
||||
|
||||
When trying to integrate GitLab with services that are using self-signed certificates,
|
||||
it is very likely that SSL certificate errors will occur on different parts of the
|
||||
application, most likely Sidekiq. There are 2 approaches you can take to solve this:
|
||||
|
||||
1. Add the root certificate to the trusted chain of the OS.
|
||||
1. If using Omnibus, you can add the certificate to GitLab's trusted certificates.
|
||||
|
||||
**OS main trusted chain**
|
||||
|
||||
This [resource](http://kb.kerio.com/product/kerio-connect/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html)
|
||||
has all the information you need to add a certificate to the main trusted chain.
|
||||
|
||||
This [answer](http://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu)
|
||||
at SuperUser also has relevant information.
|
||||
|
||||
**Omnibus Trusted Chain**
|
||||
|
||||
It is enough to concatenate the certificate to the main trusted certificate:
|
||||
|
||||
```bash
|
||||
cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem
|
||||
```
|
||||
|
||||
After that restart GitLab with:
|
||||
|
||||
```bash
|
||||
sudo gitlab-ctl restart
|
||||
```
|
||||
|
|
|
@ -204,3 +204,30 @@ When setting `method: ssl`, the underlying authentication method used by
|
|||
`omniauth-ldap` is `simple_tls`. This method establishes TLS encryption with
|
||||
the LDAP server before any LDAP-protocol data is exchanged but no validation of
|
||||
the LDAP server's SSL certificate is performed.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common problems
|
||||
|
||||
**Invalid credentials when logging in**
|
||||
|
||||
Make sure the user you are binding with has enough permissions to read the user's
|
||||
tree and traverse it.
|
||||
|
||||
Also make sure that the `user_filter` is not blocking otherwise valid users.
|
||||
|
||||
To make sure that the LDAP settings are correct and GitLab can see your users,
|
||||
execute the following command:
|
||||
|
||||
For Omnibus installations:
|
||||
|
||||
```bash
|
||||
sudo gitlab-rake gitlab:ldap:check
|
||||
```
|
||||
|
||||
For installations from source:
|
||||
|
||||
```bash
|
||||
sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
|
||||
```
|
||||
|
||||
|
|
|
@ -133,12 +133,18 @@ will be returned to GitLab and will be signed in.
|
|||
|
||||
## Troubleshooting
|
||||
|
||||
### Common problems
|
||||
|
||||
**500 error after login**
|
||||
|
||||
If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page,
|
||||
this likely indicates that GitLab could not get the email address for the SAML user.
|
||||
|
||||
Make sure the IdP provides a claim containing the user's email address, using claim name
|
||||
`email` or `mail`.
|
||||
|
||||
**Redirect back to login screen with no evident error**
|
||||
|
||||
If after signing in into your SAML server you are redirected back to the sign in page and
|
||||
no error is displayed, check your `production.log` file. It will most likely contain the
|
||||
message `Can't verify CSRF token authenticity`. This means that there is an error during
|
||||
|
@ -147,4 +153,36 @@ the SAML request, but this error never reaches GitLab due to the CSRF check.
|
|||
To bypass this you can add `skip_before_action :verify_authenticity_token` to the
|
||||
`omniauth_callbacks_controller.rb` file. This will allow the error to hit GitLab,
|
||||
where it can then be seen in the usual logs, or as a flash message in the login
|
||||
screen.
|
||||
screen.
|
||||
|
||||
**Invalid audience**
|
||||
|
||||
This error means that the IdP doesn't recognize GitLab as a valid sender and
|
||||
receiver of SAML requests. Make sure to add the GitLab callback URL to the approved
|
||||
audiences of the IdP server.
|
||||
|
||||
**Missing claims**
|
||||
|
||||
The IdP server needs to pass certain information in order for GitLab to either
|
||||
create an account, or match the login information to an existing account. `email`
|
||||
is the minimum amount of information that needs to be passed. If the IdP server
|
||||
is not providing this information, all SAML requests will fail.
|
||||
|
||||
Make sure this information is provided.
|
||||
|
||||
**Key validation error, Digest mismatch or Fingerprint mismatch**
|
||||
|
||||
These errors all come from a similar place, the SAML certificate. SAML requests
|
||||
need to be validated using a fingerprint, a certificate or a validator.
|
||||
|
||||
For this you need take the following into account:
|
||||
|
||||
- If no certificate is provided in the settings, a fingerprint or fingerprint
|
||||
validator needs to be provided and the response from the server must contain
|
||||
a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`)
|
||||
- If a certificate is provided in the settings, it is no longer necessary for
|
||||
the request to contain one. In this case the fingerprint or fingerprint
|
||||
validators are optional
|
||||
|
||||
Make sure that one of the above described scenarios is valid, or the requests will
|
||||
fail with one of the mentioned errors.
|
|
@ -219,3 +219,16 @@ You can see from the above image that there are four references to GitLab:
|
|||
[JIRA Core]: https://www.atlassian.com/software/jira/core "The JIRA Core website"
|
||||
[jira-ce]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2146 "MR - Backport JIRA service"
|
||||
[8_3_post]: https://about.gitlab.com/2015/12/22/gitlab-8-3-released/ "GitLab 8.3 release post"
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**GitLab is unable to comment on a ticket**
|
||||
|
||||
Make sure that the user you set up for GitLab to communicate with JIRA has the
|
||||
correct access permission to post comments on a ticket and to also transition the
|
||||
ticket, if you'd like GitLab to also take care of closing them.
|
||||
|
||||
**GitLab is unable to close a ticket**
|
||||
|
||||
Make sure the the `Transition ID` you set within the JIRA settings matches the
|
||||
one your project needs to close a ticket.
|
||||
|
|
|
@ -9,7 +9,8 @@ Documentation on how to use Git LFS are under [Managing large binary files with
|
|||
|
||||
## Configuration
|
||||
|
||||
Git LFS objects can be large in size. By default, they are stored on the server GitLab is installed on.
|
||||
Git LFS objects can be large in size. By default, they are stored on the server
|
||||
GitLab is installed on.
|
||||
|
||||
There are two configuration options to help GitLab server administrators:
|
||||
|
||||
|
@ -37,5 +38,8 @@ In `config/gitlab.yml`:
|
|||
|
||||
## Known limitations
|
||||
|
||||
* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets) is not supported
|
||||
* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets)
|
||||
is not supported
|
||||
* Currently, removing LFS objects from GitLab Git LFS storage is not supported
|
||||
* LFS authentications via SSH is not supported for the time being
|
||||
* Only compatible with the GitLFS client versions 1.1.0 or 1.0.2.
|
||||
|
|
|
@ -1,17 +1,21 @@
|
|||
# Git LFS
|
||||
|
||||
Managing large files such as audio, video and graphics files has always been one of the shortcomings of Git.
|
||||
The general recommendation is to not have Git repositories larger than 1GB to preserve performance.
|
||||
Managing large files such as audio, video and graphics files has always been one
|
||||
of the shortcomings of Git. The general recommendation is to not have Git repositories
|
||||
larger than 1GB to preserve performance.
|
||||
|
||||
GitLab already supports [managing large files with git annex](http://doc.gitlab.com/ee/workflow/git_annex.html) (EE only), however in certain
|
||||
environments it is not always convenient to use different commands to differentiate between the large files and regular ones.
|
||||
GitLab already supports [managing large files with git annex](http://doc.gitlab.com/ee/workflow/git_annex.html)
|
||||
(EE only), however in certain environments it is not always convenient to use
|
||||
different commands to differentiate between the large files and regular ones.
|
||||
|
||||
Git LFS makes this simpler for the end user by removing the requirement to learn new commands.
|
||||
Git LFS makes this simpler for the end user by removing the requirement to
|
||||
learn new commands.
|
||||
|
||||
## How it works
|
||||
|
||||
Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication to authorize client requests.
|
||||
Once the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file.
|
||||
Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication
|
||||
to authorize client requests. Once the request is authorized, Git LFS client receives
|
||||
instructions from where to fetch or where to push the large file.
|
||||
|
||||
## GitLab server configuration
|
||||
|
||||
|
@ -24,15 +28,19 @@ Documentation for GitLab instance administrators is under [LFS administration do
|
|||
|
||||
## Known limitations
|
||||
|
||||
* Git LFS v1 original API is not supported since it was deprecated early in LFS development
|
||||
* Git LFS v1 original API is not supported since it was deprecated early in LFS
|
||||
development
|
||||
* When SSH is set as a remote, Git LFS objects still go through HTTPS
|
||||
* Any Git LFS request will ask for HTTPS credentials to be provided so good Git credentials store is recommended
|
||||
* Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git config manually (see #troubleshooting)
|
||||
* Any Git LFS request will ask for HTTPS credentials to be provided so good Git
|
||||
credentials store is recommended
|
||||
* Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have
|
||||
to add the URL to Git config manually (see #troubleshooting)
|
||||
|
||||
## Using Git LFS
|
||||
|
||||
Lets take a look at the workflow when you need to check large files into your Git repository with Git LFS:
|
||||
For example, if you want to upload a very large file and check it into your Git repository:
|
||||
Lets take a look at the workflow when you need to check large files into your Git
|
||||
repository with Git LFS. For example, if you want to upload a very large file and
|
||||
check it into your Git repository:
|
||||
|
||||
```bash
|
||||
git clone git@gitlab.example.com:group/project.git
|
||||
|
@ -40,7 +48,8 @@ git lfs init # initialize the Git LFS project project
|
|||
git lfs track "*.iso" # select the file extensions that you want to treat as large files
|
||||
```
|
||||
|
||||
Once a certain file extension is marked for tracking as a LFS object you can use Git as usual without having to redo the command to track a file with the same extension:
|
||||
Once a certain file extension is marked for tracking as a LFS object you can use
|
||||
Git as usual without having to redo the command to track a file with the same extension:
|
||||
|
||||
```bash
|
||||
cp ~/tmp/debian.iso ./ # copy a large file into the current directory
|
||||
|
@ -49,13 +58,17 @@ git commit -am "Added Debian iso" # commit the file meta data
|
|||
git push origin master # sync the git repo and large file to the GitLab server
|
||||
```
|
||||
|
||||
Cloning the repository works the same as before. Git automatically detects the LFS-tracked files and clones them via HTTP. If you performed the git clone command with a SSH URL, you have to enter your GitLab credentials for HTTP authentication.
|
||||
Cloning the repository works the same as before. Git automatically detects the
|
||||
LFS-tracked files and clones them via HTTP. If you performed the git clone
|
||||
command with a SSH URL, you have to enter your GitLab credentials for HTTP
|
||||
authentication.
|
||||
|
||||
```bash
|
||||
git clone git@gitlab.example.com:group/project.git
|
||||
```
|
||||
|
||||
If you already cloned the repository and you want to get the latest LFS object that are on the remote repository, eg. from branch `master`:
|
||||
If you already cloned the repository and you want to get the latest LFS object
|
||||
that are on the remote repository, eg. from branch `master`:
|
||||
|
||||
```bash
|
||||
git lfs fetch master
|
||||
|
@ -73,8 +86,8 @@ Check if you have permissions to push to the project or fetch from the project.
|
|||
|
||||
* Project is not allowed to access the LFS object
|
||||
|
||||
LFS object you are trying to push to the project or fetch from the project is not available to the project anymore.
|
||||
Probably the object was removed from the server.
|
||||
LFS object you are trying to push to the project or fetch from the project is not
|
||||
available to the project anymore. Probably the object was removed from the server.
|
||||
|
||||
* Local git repository is using deprecated LFS API
|
||||
|
||||
|
@ -89,16 +102,26 @@ git lfs logs last
|
|||
|
||||
If the status `error 501` is shown, it is because:
|
||||
|
||||
* Git LFS support is not enabled on the GitLab server. Check with your GitLab administrator why Git LFS is not enabled on the server. See [LFS administration documentation](lfs_administration.md) for instructions on how to enable LFS support.
|
||||
* Git LFS support is not enabled on the GitLab server. Check with your GitLab
|
||||
administrator why Git LFS is not enabled on the server. See
|
||||
[LFS administration documentation](lfs_administration.md) for instructions
|
||||
on how to enable LFS support.
|
||||
|
||||
* Git LFS client version is not supported by GitLab server. Check your Git LFS version with `git lfs version`. Check the Git config of the project for traces of deprecated API with `git lfs -l`. If `batch = false` is set in the config, remove the line and try to update your Git LFS client. Only version 1.0.1 and newer are supported.
|
||||
* Git LFS client version is not supported by GitLab server. Check your Git LFS
|
||||
version with `git lfs version`. Check the Git config of the project for traces
|
||||
of deprecated API with `git lfs -l`. If `batch = false` is set in the config,
|
||||
remove the line and try to update your Git LFS client. Only version 1.0.1 and
|
||||
newer are supported.
|
||||
|
||||
### getsockopt: connection refused
|
||||
|
||||
If you push a LFS object to a project and you receive an error similar to: `Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`,
|
||||
the LFS client is trying to reach GitLab through HTTPS. However, your GitLab instance is being served on HTTP.
|
||||
If you push a LFS object to a project and you receive an error similar to:
|
||||
`Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`,
|
||||
the LFS client is trying to reach GitLab through HTTPS. However, your GitLab
|
||||
instance is being served on HTTP.
|
||||
|
||||
This behaviour is caused by Git LFS using HTTPS connections by default when a `lfsurl` is not set in the Git config.
|
||||
This behaviour is caused by Git LFS using HTTPS connections by default when a
|
||||
`lfsurl` is not set in the Git config.
|
||||
|
||||
To prevent this from happening, set the lfs url in project Git config:
|
||||
|
||||
|
@ -109,18 +132,24 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs/o
|
|||
|
||||
### Credentials are always required when pushing an object
|
||||
|
||||
Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing the LFS object on every push for every object, user HTTPS credentials are required.
|
||||
Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing
|
||||
the LFS object on every push for every object, user HTTPS credentials are required.
|
||||
|
||||
By default, Git has support for remembering the credentials for each repository you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials).
|
||||
By default, Git has support for remembering the credentials for each repository
|
||||
you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials).
|
||||
|
||||
For example, you can tell Git to remember the password for a period of time in which you expect to push the objects:
|
||||
For example, you can tell Git to remember the password for a period of time in
|
||||
which you expect to push the objects:
|
||||
|
||||
```bash
|
||||
git config --global credential.helper 'cache --timeout=3600'
|
||||
```
|
||||
|
||||
This will remember the credentials for an hour after which Git operations will require re-authentication.
|
||||
This will remember the credentials for an hour after which Git operations will
|
||||
require re-authentication.
|
||||
|
||||
If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases).
|
||||
If you are using OS X you can use `osxkeychain` to store and encrypt your credentials.
|
||||
For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases).
|
||||
|
||||
More details about various methods of storing the user credentials can be found on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
|
||||
More details about various methods of storing the user credentials can be found
|
||||
on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
|
Loading…
Reference in New Issue