diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/builds.md | 24 | ||||
| -rw-r--r-- | doc/development/README.md | 1 | ||||
| -rw-r--r-- | doc/development/licensing.md | 93 | ||||
| -rw-r--r-- | doc/profile/2fa_u2f_authenticate.png | bin | 0 -> 54413 bytes | |||
| -rw-r--r-- | doc/profile/2fa_u2f_register.png | bin | 0 -> 112414 bytes | |||
| -rw-r--r-- | doc/profile/two_factor_authentication.md | 63 |
6 files changed, 175 insertions, 6 deletions
diff --git a/doc/api/builds.md b/doc/api/builds.md index 4c0a47d1ea0..5669bd0cdda 100644 --- a/doc/api/builds.md +++ b/doc/api/builds.md @@ -278,6 +278,30 @@ Response: [ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893 +## Get a trace file + +Get a trace of a specific build of a project + +``` +GET /projects/:id/builds/:build_id/trace +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| id | integer | yes | The ID of a project | +| build_id | integer | yes | The ID of a build | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8/trace" +``` + +Response: + +| Status | Description | +|-----------|-----------------------------------| +| 200 | Serves the trace file | +| 404 | Build not found or no trace file | + ## Cancel a build Cancel a single build of a project diff --git a/doc/development/README.md b/doc/development/README.md index aa7d54c01d0..c5d5af43864 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -7,6 +7,7 @@ - [Gotchas](gotchas.md) to avoid - [How to dump production data to staging](db_dump.md) - [Instrumentation](instrumentation.md) +- [Licensing](licensing.md) for ensuring license compliance - [Migration Style Guide](migration_style_guide.md) for creating safe migrations - [Performance guidelines](performance.md) - [Rake tasks](rake_tasks.md) for development diff --git a/doc/development/licensing.md b/doc/development/licensing.md new file mode 100644 index 00000000000..8c8c7486fff --- /dev/null +++ b/doc/development/licensing.md @@ -0,0 +1,93 @@ +# GitLab Licensing and Compatibility + +GitLab CE is licensed under the terms of the MIT License. GitLab EE is licensed under "The GitLab Enterprise Edition (EE) license" wherein there are more restrictions. See their respective LICENSE files ([CE][CE], [EE][EE]) for more information. + +## Automated Testing + +In order to comply with the terms the libraries we use are licensed under, we have to make sure to check new gems for compatible licenses whenever they're added. To automate this process, we use the [license_finder][license_finder] gem by Pivotal. It runs every time a new commit is pushed and verifies that all gems in the bundle use a license that doesn't conflict with the licensing of either GitLab Community Edition or GitLab Enterprise Edition. + +There are some limitations with the automated testing, however. CSS and JavaScript libraries, as well as any Ruby libraries not included by way of Bundler, must be verified manually and independently. Take care whenever one such library is used, as automated tests won't catch problematic licenses from them. + +Some gems may not include their license information in their `gemspec` file. These won't be detected by License Finder, and will have to be verified manually. + +### License Finder commands + +There are a few basic commands License Finder provides that you'll need in order to manage license detection. + +To verify that the checks are passing, and/or to see what dependencies are causing the checks to fail: + +``` +bundle exec license_finder +``` + +To whitelist a new license: + +``` +license_finder whitelist add MIT +``` + +To blacklist a new license: + +``` +license_finder blacklist add GPLv2 +``` + +To tell License Finder about a dependency's license if it isn't auto-detected: + +``` +license_finder licenses add my_unknown_dependency MIT +``` + +For all of the above, please include `--why "Reason"` and `--who "My Name"` so the `decisions.yml` file can keep track of when, why, and who approved of a dependency. + +More detailed information on how the gem and its commands work is available in the [License Finder README][license_finder]. + +## Acceptable Licenses + +Libraries with the following licenses are acceptable for use: + +- [The MIT License][MIT] (the MIT Expat License specifically): The MIT License requires that the license itself is included with all copies of the source. It is a permissive (non-copyleft) license as defined by the Open Source Initiative. +- [LGPL][LGPL] (version 2, version 3): GPL constraints regarding modification and redistribution under the same license are not required of projects using an LGPL library, only upon modification of the LGPL-licensed library itself. +- [Apache 2.0 License][apache-2]: A permissive license that also provides an express grant of patent rights from contributors to users. +- [Ruby 1.8 License][ruby-1.8]: Dual-licensed under either itself or the GPLv2, defer to the Ruby License itself. Acceptable because of point 3b: "You may distribute the software in object code or binary form, provided that you do at least ONE of the following: b) accompany the distribution with the machine-readable source of the software." +- [Ruby 1.9 License][ruby-1.9]: Dual-licensed under either itself or the BSD 2-Clause License, defer to BSD 2-Clause. +- [BSD 2-Clause License][BSD-2-Clause]: A permissive (non-copyleft) license as defined by the Open Source Initiative. +- [BSD 3-Clause License][BSD-3-Clause] (also known as New BSD or Modified BSD): A permissive (non-copyleft) license as defined by the Open Source Initiative +- [ISC License][ISC] (also known as the OpenBSD License): A permissive (non-copyleft) license as defined by the Open Source Initiative. + +## Unacceptable Licenses + +Libraries with the following licenses are unacceptable for use: + +- [GNU GPL][GPL] (version 1, [version 2][GPLv2], [version 3][GPLv3], or any future versions): GPL-licensed libraries cannot be linked to from non-GPL projects. +- [GNU AGPLv3][AGPLv3]: AGPL-licensed libraries cannot be linked to from non-GPL projects. + +## Notes + +Decisions regarding the GNU GPL licenses are based on information provided by [The GNU Project][GNU-GPL-FAQ], as well as [the Open Source Initiative][OSI-GPL], which both state that linking GPL libraries makes the program itself GPL. + +If a gem uses a license which is not listed above, open an issue and ask. If a license is not included in the "acceptable" list, operate under the assumption that it is not acceptable. + +Keep in mind that each license has its own restrictions (typically defined in their body text). Please make sure to comply with those restrictions at all times whenever an external library is used. + +Gems which are included only in the "development" or "test" groups by Bundler are exempt from license requirements, as they're not distributed for use in production. + +**NOTE:** This document is **not** legal advice, nor is it comprehensive. It should not be taken as such. + +[CE]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/LICENSE +[EE]: https://gitlab.com/gitlab-org/gitlab-ee/blob/master/LICENSE +[license_finder]: https://github.com/pivotal/LicenseFinder +[MIT]: http://choosealicense.com/licenses/mit/ +[LGPL]: http://choosealicense.com/licenses/lgpl-3.0/ +[apache-2]: http://choosealicense.com/licenses/apache-2.0/ +[ruby-1.8]: https://github.com/ruby/ruby/blob/ruby_1_8_6/COPYING +[ruby-1.9]: https://www.ruby-lang.org/en/about/license.txt +[BSD-2-Clause]: https://opensource.org/licenses/BSD-2-Clause +[BSD-3-Clause]: https://opensource.org/licenses/BSD-3-Clause +[ISC]: https://opensource.org/licenses/ISC +[GPL]: http://choosealicense.com/licenses/gpl-3.0/ +[GPLv2]: http://www.gnu.org/licenses/gpl-2.0.txt +[GPLv3]: http://www.gnu.org/licenses/gpl-3.0.txt +[AGPLv3]: http://choosealicense.com/licenses/agpl-3.0/ +[GNU-GPL-FAQ]: http://www.gnu.org/licenses/gpl-faq.html#IfLibraryIsGPL +[OSI-GPL]: https://opensource.org/faq#linking-proprietary-code diff --git a/doc/profile/2fa_u2f_authenticate.png b/doc/profile/2fa_u2f_authenticate.png Binary files differnew file mode 100644 index 00000000000..b9138ff60db --- /dev/null +++ b/doc/profile/2fa_u2f_authenticate.png diff --git a/doc/profile/2fa_u2f_register.png b/doc/profile/2fa_u2f_register.png Binary files differnew file mode 100644 index 00000000000..15b3683ef73 --- /dev/null +++ b/doc/profile/2fa_u2f_register.png diff --git a/doc/profile/two_factor_authentication.md b/doc/profile/two_factor_authentication.md index a0e23c1586c..82505b13401 100644 --- a/doc/profile/two_factor_authentication.md +++ b/doc/profile/two_factor_authentication.md @@ -8,12 +8,27 @@ your phone. By enabling 2FA, the only way someone other than you can log into your account is to know your username and password *and* have access to your phone. -#### Note +> **Note:** When you enable 2FA, don't forget to back up your recovery codes. For your safety, if you lose your codes for GitLab.com, we can't disable or recover them. +In addition to a phone application, GitLab supports U2F (universal 2nd factor) devices as +the second factor of authentication. Once enabled, in addition to supplying your username and +password to login, you'll be prompted to activate your U2F device (usually by pressing +a button on it), and it will perform secure authentication on your behalf. + +> **Note:** Support for U2F devices was added in version 8.8 + +The U2F workflow is only supported by Google Chrome at this point, so we _strongly_ recommend +that you set up both methods of two-factor authentication, so you can still access your account +from other browsers. + +> **Note:** GitLab officially only supports [Yubikey] U2F devices. + ## Enabling 2FA +### Enable 2FA via mobile application + **In GitLab:** 1. Log in to your GitLab account. @@ -38,9 +53,26 @@ lose your codes for GitLab.com, we can't disable or recover them. 1. Click **Submit**. If the pin you entered was correct, you'll see a message indicating that -Two-factor Authentication has been enabled, and you'll be presented with a list +Two-Factor Authentication has been enabled, and you'll be presented with a list of recovery codes. +### Enable 2FA via U2F device + +**In GitLab:** + +1. Log in to your GitLab account. +1. Go to your **Profile Settings**. +1. Go to **Account**. +1. Click **Enable Two-Factor Authentication**. +1. Plug in your U2F device. +1. Click on **Setup New U2F Device**. +1. A light will start blinking on your device. Activate it by pressing its button. + +You will see a message indicating that your device was successfully set up. +Click on **Register U2F Device** to complete the process. + + + ## Recovery Codes Should you ever lose access to your phone, you can use one of the ten provided @@ -51,21 +83,39 @@ account. If you lose the recovery codes or just want to generate new ones, you can do so from the **Profile Settings** > **Account** page where you first enabled 2FA. +> **Note:** Recovery codes are not generated for U2F devices. + ## Logging in with 2FA Enabled Logging in with 2FA enabled is only slightly different than a normal login. Enter your username and password credentials as you normally would, and you'll -be presented with a second prompt for an authentication code. Enter the pin from -your phone's application or a recovery code to log in. +be presented with a second prompt, depending on which type of 2FA you've enabled. + +### Log in via mobile application + +Enter the pin from your phone's application or a recovery code to log in. - + + +### Log in via U2F device + +1. Click **Login via U2F Device** +1. A light will start blinking on your device. Activate it by pressing its button. + +You will see a message indicating that your device responded to the authentication request. +Click on **Authenticate via U2F Device** to complete the process. + + ## Disabling 2FA 1. Log in to your GitLab account. 1. Go to your **Profile Settings**. 1. Go to **Account**. -1. Click **Disable Two-factor Authentication**. +1. Click **Disable**, under **Two-Factor Authentication**. + +This will clear all your two-factor authentication registrations, including mobile +applications and U2F devices. ## Note to GitLab administrators @@ -74,3 +124,4 @@ You need to take special care to that 2FA keeps working after [Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en [FreeOTP]: https://fedorahosted.org/freeotp/ +[YubiKey]: https://www.yubico.com/products/yubikey-hardware/ |
