diff options
Diffstat (limited to 'doc/tutorials')
28 files changed, 1228 insertions, 95 deletions
diff --git a/doc/tutorials/agile_sprint.md b/doc/tutorials/agile_sprint.md deleted file mode 100644 index 84927fe0a66..00000000000 --- a/doc/tutorials/agile_sprint.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'agile_sprint/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](agile_sprint/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/agile_sprint/index.md b/doc/tutorials/agile_sprint/index.md index fe106af2dc2..ea4234b118f 100644 --- a/doc/tutorials/agile_sprint/index.md +++ b/doc/tutorials/agile_sprint/index.md @@ -32,7 +32,7 @@ Membership automatically cascades down to all subgroups and projects. ## Create a project -Now [create one or more projects](../../user/project/index.md#create-a-project) in your group. +Now [create one or more projects](../../user/project/index.md) in your group. There are several different ways to create a project. A project contains your code and pipelines, but also the issues that are used for planning your upcoming code changes. @@ -47,9 +47,7 @@ When creating an iteration cadence, you can decide whether to automatically mana disable the automated scheduling to [manually manage the iterations](../../user/group/iterations/index.md#manual-iteration-management). -Similar to membership, iterations cascade down your group, subgroup, and project hierarchy. If your -team works across many groups, subgroups, and projects, create the iteration cadence in the top-most -group shared by all projects that contain the team's issues as illustrated by the diagram below. +Similar to membership, iterations cascade down your group, subgroup, and project hierarchy. If your team has multiple groups and projects, create the iteration cadence in the top-most shared group: ```mermaid graph TD diff --git a/doc/tutorials/boards_for_teams/index.md b/doc/tutorials/boards_for_teams/index.md index 4e0e50971d3..c316e42d218 100644 --- a/doc/tutorials/boards_for_teams/index.md +++ b/doc/tutorials/boards_for_teams/index.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Set up issue boards for team hand-off **(PREMIUM)** +# Tutorial: Set up issue boards for team hand-off **(PREMIUM ALL)** <!-- vale gitlab.FutureTense = NO --> @@ -82,7 +82,8 @@ Prerequisites: To create a blank project: -1. In your group, on the right of the page, select **New project**. +1. In your group, on the left sidebar, at the top, select **Create new** (**{plus}**) and then select + **In this group > New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, name your project `Paperclip Assistant`. @@ -170,7 +171,7 @@ To create an issue from your board: 1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. 1. Select **UX workflow**. -1. On the `Workflow::Ready for development` list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. +1. On the `Workflow::Ready for development` list, select **Create new issue** (**{plus}**). 1. Complete the fields: 1. Under **Title**, enter `Redesign user profile page`. 1. Under **Projects**, select **Paperclip Software Factory / Paperclip Assistant**. diff --git a/doc/tutorials/build_application.md b/doc/tutorials/build_application.md index 8e53f1ccc6b..c22cba7e0e8 100644 --- a/doc/tutorials/build_application.md +++ b/doc/tutorials/build_application.md @@ -28,6 +28,7 @@ Set up runners to run jobs in a pipeline. | Topic | Description | Good for beginners | |-------|-------------|--------------------| +| [Create, register, and run your own project runner](create_register_first_runner/index.md) | Learn the basics of how to create and register a project runner that runs jobs for your project. | **{star}** | | [Configure GitLab Runner to use the Google Kubernetes Engine](configure_gitlab_runner_to_use_gke/index.md) | Learn how to configure GitLab Runner to use the GKE to run jobs. | | ## Publish a static website @@ -38,4 +39,4 @@ Use GitLab Pages to publish a static website directly from your project. |-------|-------------|--------------------| | [Create a Pages website from a CI/CD template](../user/project/pages/getting_started/pages_ci_cd_template.md) | Quickly generate a Pages website for your project using a CI/CD template for a popular Static Site Generator (SSG). | **{star}** | | [Create a Pages website from scratch](../user/project/pages/getting_started/pages_from_scratch.md) | Create all the components of a Pages website from a blank project. | | -| [Build, test, and deploy your Hugo site with GitLab](/ee/tutorials/hugo/index.md) | Generate your Hugo site using a CI/CD template and GitLab Pages. | **{star}** | +| [Build, test, and deploy your Hugo site with GitLab](../tutorials/hugo/index.md) | Generate your Hugo site using a CI/CD template and GitLab Pages. | **{star}** | diff --git a/doc/tutorials/compliance_pipeline/index.md b/doc/tutorials/compliance_pipeline/index.md index 9cf8148fe40..5396248d05a 100644 --- a/doc/tutorials/compliance_pipeline/index.md +++ b/doc/tutorials/compliance_pipeline/index.md @@ -4,7 +4,7 @@ group: Compliance info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- -# Tutorial: Create a compliance pipeline **(ULTIMATE)** +# Tutorial: Create a compliance pipeline **(ULTIMATE ALL)** You can use [compliance pipelines](../../user/group/compliance_frameworks.md#compliance-pipelines) to ensure specific compliance-related jobs are run on pipelines for all projects in a group. Compliance pipelines are applied diff --git a/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md b/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md index 05340994edf..d9a6dbbb3f0 100644 --- a/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md +++ b/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md @@ -4,7 +4,7 @@ group: Runner info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Configure GitLab Runner to use the Google Kubernetes Engine **(FREE)** +# Tutorial: Configure GitLab Runner to use the Google Kubernetes Engine **(FREE ALL)** This tutorial describes how to configure GitLab Runner to use the Google Kubernetes Engine (GKE) to run jobs. @@ -64,7 +64,7 @@ and, for autopilot clusters, to add configurations that specify which jobs to ru 1. Verify that you are connected to the cluster: ```shell - kubectl config view current-context + kubectl config current-context ``` ## Install and configure the Kubernetes Operator @@ -74,7 +74,7 @@ Now that you have a cluster, you're ready to install and configure the Kubernete 1. Install the prerequisites: ```shell - kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.yaml + kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.yaml ``` 1. Install the Operator Lifecycle Manager (OLM), a tool that manages the Kubernetes Operators that diff --git a/doc/tutorials/container_scanning/index.md b/doc/tutorials/container_scanning/index.md index 711ed359e89..d1966cbb788 100644 --- a/doc/tutorials/container_scanning/index.md +++ b/doc/tutorials/container_scanning/index.md @@ -4,7 +4,7 @@ group: Composition Analysis info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- -# Tutorial: Scan a Docker container for vulnerabilities **(FREE)** +# Tutorial: Scan a Docker container for vulnerabilities **(FREE ALL)** You can use [container scanning](../../user/application_security/container_scanning/index.md) to check for vulnerabilities in container images stored in the [container registry](../../user/packages/container_registry/index.md). diff --git a/doc/tutorials/convert_personal_namespace_into_group.md b/doc/tutorials/convert_personal_namespace_into_group.md deleted file mode 100644 index c1b3b58efb8..00000000000 --- a/doc/tutorials/convert_personal_namespace_into_group.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'convert_personal_namespace_to_group/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](convert_personal_namespace_to_group/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/create_compliance_pipeline.md b/doc/tutorials/create_compliance_pipeline.md deleted file mode 100644 index ac5550ad6a4..00000000000 --- a/doc/tutorials/create_compliance_pipeline.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'compliance_pipeline/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](compliance_pipeline/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/create_register_first_runner/index.md b/doc/tutorials/create_register_first_runner/index.md new file mode 100644 index 00000000000..05bf5cd8288 --- /dev/null +++ b/doc/tutorials/create_register_first_runner/index.md @@ -0,0 +1,167 @@ +--- +stage: Verify +group: Runner +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tutorial: Create, register, and run your own project runner **(FREE ALL)** + +This tutorial shows you how to configure and run your first runner in GitLab. + +A runner is an agent in the GitLab Runner application that runs jobs in a GitLab CI/CD pipeline. +Jobs are defined in the `.gitlab-ci.yml` file and assigned to available runners. + +GitLab has three types of runners: + +- Shared: Available to all groups and projects in a GitLab instance. +- Group: Available to all projects and subgroups in a group. +- Project: Associated with specific projects. Typically, project runners are used by one project at a time. + +For this tutorial, you'll create a project runner to run jobs defined in a basic pipeline +configuration: + +1. [Create a blank project](#create-a-blank-project) +1. [Create a project pipeline](#create-a-project-pipeline). +1. [Create and register a project runner](#create-and-register-a-project-runner). +1. [Trigger a pipeline to run your runner](#trigger-a-pipeline-to-run-your-runner). + +## Prerequisite + +Before you can create, register, and run a runner, [GitLab Runner](https://docs.gitlab.com/runner/install/) must be installed on a local computer. + +## Create a blank project + +First, create a blank project where you can create your CI/CD pipeline and runner. + +To create a blank project: + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. +1. Select **Create project**. + +## Create a project pipeline + +Next, create a `.gitlab-ci.yml` file for your project. This is a YAML file where you specify instructions for GitLab CI/CD. + +In this file, you define: + +- The structure and order of jobs that the runner should execute. +- The decisions the runner should make when specific conditions are encountered. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Project overview**. +1. Select the plus icon (**{plus}**), then select **New file**. +1. In the **Filename** field, enter `.gitlab-ci.yml`. +1. In the large text box, paste this sample configuration: + + ```yaml + stages: + - build + - test + + job_build: + stage: build + script: + - echo "Building the project" + + job_test: + stage: test + script: + - echo "Running tests" + ``` + + In this configuration there are two jobs that the runner runs: a build job and a test job. +1. Select **Commit changes**. + +## Create and register a project runner + +Next, create a project runner and register it. You must register the runner to link it +to GitLab so that it can pick up jobs from the project pipeline. + +To create a project runner: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. +1. Expand the **Runners** section. +1. Select **New project runner**. +1. Select your operating system. +1. In the **Tags** section, select the **Run untagged** checkbox. [Tags](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) specify which jobs + the runner can run and are optional. +1. Select **Create runner**. +1. Follow the on-screen instructions to register the runner from the command line. When prompted: + - For `executor`, because your runner will run directly on the host computer, enter `shell`. The [executor](https://docs.gitlab.com/runner/executors/) + is the environment where the runner executes the job. + - For `GitLab instance URL`, use the URL for your GitLab instance. For example, if your project + is hosted on `gitlab.example.com/yourname/yourproject`, then your GitLab instance URL is `https://gitlab.example.com`. + If your project is hosted on GitLab.com, the URL is `https://gitlab.com`. +1. Start your runner: + + ```shell + gitlab-runner run + ``` + +### Check the runner configuration file + +After you register the runner, the configuration and authentication token is saved to your `config.toml`. The runner uses the +token to authenticate with GitLab when picking up jobs from the job queue. + +You can use the `config.toml` to +define more [advanced runner configurations](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +Here's what your `config.toml` should look like after you register and start the runner: + +```toml + [[runners]] + name = "my-project-runner1" + url = "http://127.0.0.1:3000" + id = 38 + token = "glrt-TOKEN" + token_obtained_at = 2023-07-05T08:56:33Z + token_expires_at = 0001-01-01T00:00:00Z + executor = "shell" +``` + +## Trigger a pipeline to run your runner + +Next, trigger a pipeline in your project so you can view your runner execute a job. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Build > Pipelines**. +1. Select **Run pipeline**. +1. Select a job to view the job log. The output should look similar to this example, which shows + your runner successfully executing the job: + + ```shell + Running with gitlab-runner 16.2.0 (782e15da) + on my-project-runner TOKEN, system ID: SYSTEM ID + Preparing the "shell" executor + 00:00 + Using Shell (bash) executor... + Preparing environment + 00:00 + /Users/username/.bash_profile: line 9: setopt: command not found + Running on MACHINE-NAME... + Getting source from Git repository + 00:01 + /Users/username/.bash_profile: line 9: setopt: command not found + Fetching changes with git depth set to 20... + Reinitialized existing Git repository in /Users/username/project-repository + Checking out 7226fc70 as detached HEAD (ref is main)... + Skipping object checkout, Git LFS is not installed for this repository. + Consider installing it with 'git lfs install'. + Skipping Git submodules setup + Executing "step_script" stage of the job script + 00:00 + /Users/username/.bash_profile: line 9: setopt: command not found + $ echo "Building the project" + Building the project + Job succeeded + + ``` + +You have now successfully created, registered, and run your first runner! diff --git a/doc/tutorials/fuzz_testing/index.md b/doc/tutorials/fuzz_testing/index.md index f51f7cdb427..e4c494e9b85 100644 --- a/doc/tutorials/fuzz_testing/index.md +++ b/doc/tutorials/fuzz_testing/index.md @@ -4,7 +4,7 @@ group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Perform fuzz testing in GitLab **(ULTIMATE)** +# Tutorial: Perform fuzz testing in GitLab **(ULTIMATE ALL)** [Coverage-guided fuzz testing](../../user/application_security/coverage_fuzzing/index.md#coverage-guided-fuzz-testing-process) sends unexpected, malformed, or random data to your application, and then monitors your application for unstable behaviors and crashes. diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md deleted file mode 100644 index 74b24005077..00000000000 --- a/doc/tutorials/fuzz_testing_tutorial.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'fuzz_testing/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](fuzz_testing/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/infrastructure.md b/doc/tutorials/infrastructure.md index 688a1a1f7c7..ee4fc748c0e 100644 --- a/doc/tutorials/infrastructure.md +++ b/doc/tutorials/infrastructure.md @@ -13,3 +13,5 @@ configure the infrastructure for your application. |-------|-------------|--------------------| | [Use GitOps with GitLab](https://about.gitlab.com/blog/2022/04/07/the-ultimate-guide-to-gitops-with-gitlab/) | Learn how to provision and manage a base infrastructure, connect to a Kubernetes cluster, deploy third-party applications, and carry out other infrastructure automation tasks. | | | [Set up Flux for GitOps](../user/clusters/agent/gitops/flux_tutorial.md) | Learn how to set up Flux for GitOps in a sample project. | | +| [Deploy a Git repository using Flux](../user/clusters/agent/gitops/example_repository_structure.md) | Learn how to organize a GitLab project for GitOps. | | +| [Deploy an OCI artifact using Flux](../user/clusters/agent/gitops/flux_oci_tutorial.md) | Learn how to package and deploy your Kubernetes manifests as an OCI artifact. | | diff --git a/doc/tutorials/install_gitlab_single_node/index.md b/doc/tutorials/install_gitlab_single_node/index.md new file mode 100644 index 00000000000..5ed98ccbefc --- /dev/null +++ b/doc/tutorials/install_gitlab_single_node/index.md @@ -0,0 +1,435 @@ +--- +stage: Systems +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tutorial: Install and secure a single node GitLab instance **(FREE SELF)** + +In this tutorial you will learn how to install and securely configure a single +node GitLab instance that can accommodate up to +[1,000 users](../../administration/reference_architectures/1k_users.md). + +To install a single node GitLab instance and configure it to be secure: + +1. [Secure the server](#secure-the-server) +1. [Install GitLab](#install-gitlab) +1. [Configure GitLab](#configure-gitlab) +1. [Next steps](#next-steps) + +## Prerequisites + +- A domain name, and a correct [setup of DNS](https://docs.gitlab.com/omnibus/settings/dns.html). +- A Debian-based server with the following minimum specs: + - 8 vCPU + - 7.2 GB memory + - Enough hard drive space for all your repositories. + Read more about the + [storage requirements](../../install/requirements.md). + +## Secure the server + +Before installing GitLab, start by configuring your server to be a bit more secure. + +### Configure the firewall + +You need to open ports 22 (SSH), 80 (HTTP), and 443 (HTTPS). You can do this by +either using your cloud provider's console, or at the server level. + +In this example, you'll configure the firewall using [`ufw`](https://wiki.ubuntu.com/UncomplicatedFirewall). +You'll deny access to all ports, allow ports 80 and 443, and finally, rate limit access to port 22. +`ufw` can deny connections from an IP address that has attempted to initiate 6 or more +connections in the last 30 seconds. + +1. Install `ufw`: + + ```shell + sudo apt install ufw + ``` + +1. Enable and start the `ufw` service: + + ```shell + sudo systemctl enable --now ufw + ``` + +1. Deny all other ports except the required ones: + + ```shell + sudo ufw default deny + sudo ufw allow http + sudo ufw allow https + sudo ufw limit ssh/tcp + ``` + +1. Finally, activate the settings. The following needs to run only once, the first time + you install the package. Answer yes (`y`) when prompted: + + ```shell + sudo ufw enable + ``` + +1. Verify that the rules are present: + + ```shell + $ sudo ufw status + + Status: active + + To Action From + -- ------ ---- + 80/tcp ALLOW Anywhere + 443 ALLOW Anywhere + 22/tcp LIMIT Anywhere + 80/tcp (v6) ALLOW Anywhere (v6) + 443 (v6) ALLOW Anywhere (v6) + 22/tcp (v6) LIMIT Anywhere (v6) + ``` + +### Configure the SSH server + +To further secure your server, configure SSH to accept public key authentication, +and disable some features that are potential security risks. + +1. Open `/etc/ssh/sshd_config` with your editor and make sure the following are present: + + ```plaintext + PubkeyAuthentication yes + PasswordAuthentication yes + UsePAM yes + UseDNS no + AllowTcpForwarding no + X11Forwarding no + PrintMotd no + PermitTunnel no + # Allow client to pass locale environment variables + AcceptEnv LANG LC_* + # override default of no subsystems + Subsystem sftp /usr/lib/openssh/sftp-server + # Protocol adjustments, these would be needed/recommended in a FIPS or + # FedRAMP deployment, and use only strong and proven algorithm choices + Protocol 2 + Ciphers aes128-ctr,aes192-ctr,aes256-ctr + HostKeyAlgorithms ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521 + KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521 + Macs hmac-sha2-256,hmac-sha2-512 + ``` + +1. Save the file and restart the SSH server: + + ```shell + sudo systemctl restart ssh + ``` + + If restarting SSH fails, check that you don't have any + duplicate entries in `/etc/ssh/sshd_config`. + +### Ensure only authorized users are using SSH for Git access + +Next, ensure that users cannot pull down projects using SSH unless they have a +valid GitLab account that can perform Git operations over SSH. + +To ensure that only authorized users are using SSH for Git access: + +1. Add the following to your `/etc/ssh/sshd_config` file: + + ```plaintext + # Ensure only authorized users are using Git + AcceptEnv GIT_PROTOCOL + ``` + +1. Save the file and restart the SSH server: + + ```shell + sudo systemctl restart ssh + ``` + +### Make some kernel adjustments + +Kernel adjustments do not completely eliminate the threat of an attack, but +they add an extra layer of security. + +1. Open a new file with your editor under `/etc/sysctl.d`, for example + `/etc/sysctl.d/99-gitlab-hardening.conf`, and add the following. + + NOTE: + The naming and source directory decide the order of processing, which is + important because the last parameter processed might override earlier ones. + + ```plaintext + ## + ## The following help mitigate out of bounds, null pointer dereference, heap and + ## buffer overflow bugs, use-after-free etc from being exploited. It does not 100% + ## fix the issues, but seriously hampers exploitation. + ## + # Default is 65536, 4096 helps mitigate memory issues used in exploitation + vm.mmap_min_addr=4096 + # Default is 0, randomize virtual address space in memory, makes vuln exploitation + # harder + kernel.randomize_va_space=2 + # Restrict kernel pointer access (for example, cat /proc/kallsyms) for exploit assistance + kernel.kptr_restrict=2 + # Restrict verbose kernel errors in dmesg + kernel.dmesg_restrict=1 + # Restrict eBPF + kernel.unprivileged_bpf_disabled=1 + net.core.bpf_jit_harden=2 + # Prevent common use-after-free exploits + vm.unprivileged_userfaultfd=0 + + ## Networking tweaks ## + ## + ## Prevent common attacks at the IP stack layer + ## + # Prevent SYNFLOOD denial of service attacks + net.ipv4.tcp_syncookies=1 + # Prevent time wait assassination attacks + net.ipv4.tcp_rfc1337=1 + # IP spoofing/source routing protection + net.ipv4.conf.all.rp_filter=1 + net.ipv4.conf.default.rp_filter=1 + net.ipv6.conf.all.accept_ra=0 + net.ipv6.conf.default.accept_ra=0 + net.ipv4.conf.all.accept_source_route=0 + net.ipv4.conf.default.accept_source_route=0 + net.ipv6.conf.all.accept_source_route=0 + net.ipv6.conf.default.accept_source_route=0 + # IP redirection protection + net.ipv4.conf.all.accept_redirects=0 + net.ipv4.conf.default.accept_redirects=0 + net.ipv4.conf.all.secure_redirects=0 + net.ipv4.conf.default.secure_redirects=0 + net.ipv6.conf.all.accept_redirects=0 + net.ipv6.conf.default.accept_redirects=0 + net.ipv4.conf.all.send_redirects=0 + net.ipv4.conf.default.send_redirects=0 + ``` + +1. On the next server reboot, the values will be loaded automatically. To load + them immediately: + + ```shell + sudo sysctl --system + ``` + +Great work, you've completed the steps to secure your server! +Now you're ready to install GitLab. + +## Install GitLab + +Now that your server is set up, install GitLab: + +1. Install and configure the necessary dependencies: + + ```shell + sudo apt update + sudo apt install -y curl openssh-server ca-certificates perl locales + ``` + +1. Configure the system language: + + 1. Edit `/etc/locale.gen` and make sure `en_US.UTF-8` is uncommented. + 1. Regenerate the languages: + + ```shell + sudo locale-gen + ``` + +1. Add the GitLab package repository and install the package: + + ```shell + curl "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh" | sudo bash + ``` + + To see the contents of the script, visit <https://packages.gitlab.com/gitlab/gitlab-ee/install>. + +1. Install the GitLab package. Provide a strong password with + `GITLAB_ROOT_PASSWORD` and replace the `EXTERNAL_URL` + with your own. Don't forget to include `https` in the URL, so that a Let's Encrypt + certificate is issued. + + ```shell + sudo GITLAB_ROOT_PASSWORD="strong password" EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ee + ``` + + To learn more about the Let's Encrypt certificate or even + use your own, read how to [configure GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl/). + + If the password you set wasn't picked up, read more about + [resetting the root account password](../../security/reset_user_password.md). + +1. After a few minutes, GitLab is installed. Sign in + using the URL you set up in `EXTERNAL_URL`. Use `root` as the username and + the password you set up in `GITLAB_ROOT_PASSWORD`. + +Now it's time to configure GitLab! + +## Configure GitLab + +GitLab comes with some sane default configuration options. In this section, +we will change them to add more functionality, and make GitLab more secure. + +For some of the options you'll use the Admin Area UI, and for some of them you'll +edit `/etc/gitlab/gitlab.rb`, the GitLab configuration file. + +### Configure NGINX + +NGINX is used to serve up the web interface used to access the GitLab instance. +For more information about configuring NGINX to be more secure, read about +[hardening NGINX](../../security/hardening_configuration_recommendations.md#nginx). + +### Configure emails + +Next, you'll set up and configure an email service. Emails are important for +verifying new sign ups, resetting passwords, and notifying +you of GitLab activity. + +#### Configure SMTP + +In this tutorial, you'll set up an [SMTP](https://docs.gitlab.com/omnibus/settings/smtp.html) +server and use the [Mailgun](https://mailgun.com) SMTP provider. + +First, start by creating an encrypted file that will contain the login +credentials, and then configure SMTP for the Linux package: + +1. Create a YAML file (for example `smtp.yaml`) that contains the credentials + for the SMTP server. + + Your SMTP password must not contain any string delimiters used in + Ruby or YAML (for example, `'`) to avoid unexpected behavior during the + processing of configuration settings. + + ```shell + user_name: '<SMTP user>' + password: '<SMTP password>' + ``` + +1. Encrypt the file: + + ```shell + cat smtp.yaml | sudo gitlab-rake gitlab:smtp:secret:write + ``` + + By default, the encrypted file is stored under + `/var/opt/gitlab/gitlab-rails/shared/encrypted_configuration/smtp.yaml.enc`. + +1. Remove the YAML file: + + ```shell + rm -f smtp.yaml + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and set up the rest of the SMTP settings. + Make sure `gitlab_rails['smtp_user_name']` and `gitlab_rails['smtp_password']` + are **not** present, as we've already set them up as encrypted. + + ```ruby + gitlab_rails['smtp_enable'] = true + gitlab_rails['smtp_address'] = "smtp.mailgun.org" # or smtp.eu.mailgun.org + gitlab_rails['smtp_port'] = 587 + gitlab_rails['smtp_authentication'] = "plain" + gitlab_rails['smtp_enable_starttls_auto'] = true + gitlab_rails['smtp_domain'] = "<mailgun domain>" + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +You should now be able to send emails. To test that the configuration worked: + +1. Enter the Rails console: + + ```shell + sudo gitlab-rails console + ``` + +1. Run the following command at the console prompt to make GitLab send a test email: + + ```irb + Notify.test_email('<email_address>', 'Message Subject', 'Message Body').deliver_now + ``` + +If you're unable to send emails, see the +[SMTP troubleshooting section](https://docs.gitlab.com/omnibus/settings/smtp.html#troubleshooting). + +#### Enable the email verification + +Account email verification provides an additional layer of GitLab account +security. When some conditions are met, for example, if there are three or more +failed sign-in attempts in 24 hours, an account is locked. + +This feature is behind a feature flag. To enable it: + +1. Enter the Rails console: + + ```shell + sudo gitlab-rails console + ``` + +1. Enable the feature flag: + + ```ruby + Feature.enable(:require_email_verification) + ``` + +1. Check if it's enabled (should return `true`): + + ```ruby + Feature.enabled?(:require_email_verification) + ``` + +For more information, read about +[account email verification](../../security/email_verification.md). + +#### Sign outgoing email with S/MIME + +Notification emails sent by GitLab can be signed with +[S/MIME](https://en.wikipedia.org/wiki/S/MIME) for improved security. + +A single pair of key and certificate files must be provided: + +- Both files must be PEM-encoded. +- The key file must be unencrypted so that GitLab can read it without user intervention. +- Only RSA keys are supported. +- Optional. You can provide a bundle of Certificate Authority (CA) certs + (PEM-encoded) to include on each signature. This is typically an + intermediate CA. + +1. Buy your certificate from a CA. +1. Edit `/etc/gitlab/gitlab.rb` and adapt the file paths: + + ```ruby + gitlab_rails['gitlab_email_smime_enabled'] = true + gitlab_rails['gitlab_email_smime_key_file'] = '/etc/gitlab/ssl/gitlab_smime.key' + gitlab_rails['gitlab_email_smime_cert_file'] = '/etc/gitlab/ssl/gitlab_smime.crt' + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +For more information, read about +[signing outgoing email with S/MIME](../../administration/smime_signing_email.md). + +## Next steps + +In this tutorial, you learned how to set up your server to be more secure, how +to install GitLab, and how to configure GitLab to meet some security standards. +Some [other steps](../../security/hardening_application_recommendations.md) you can take to secure GitLab include: + +- Disabling sign ups. By default, a new GitLab instance has sign up enabled by default. If you don't + plan to make your GitLab instance public, you should to disable sign ups. +- Allowing or denying sign ups using specific email domains. +- Setting a minimum password length limit for new users. +- Enforcing two-factor authentication for all users. + +There are many other things you can configure apart from hardening your GitLab +instance, like configuring your own runners to leverage the CI/CD features that +GitLab has to offer, or properly backing up your instance. + +You can read more about the [steps to take after the installation](../../install/next_steps.md). diff --git a/doc/tutorials/issue_triage/img/priority_labels_v16_3.png b/doc/tutorials/issue_triage/img/priority_labels_v16_3.png Binary files differnew file mode 100644 index 00000000000..afcf1752955 --- /dev/null +++ b/doc/tutorials/issue_triage/img/priority_labels_v16_3.png diff --git a/doc/tutorials/issue_triage/img/triage_board_v16_3.png b/doc/tutorials/issue_triage/img/triage_board_v16_3.png Binary files differnew file mode 100644 index 00000000000..c32352a454e --- /dev/null +++ b/doc/tutorials/issue_triage/img/triage_board_v16_3.png diff --git a/doc/tutorials/issue_triage/img/triage_report_v16_3.png b/doc/tutorials/issue_triage/img/triage_report_v16_3.png Binary files differnew file mode 100644 index 00000000000..91548a1a17d --- /dev/null +++ b/doc/tutorials/issue_triage/img/triage_report_v16_3.png diff --git a/doc/tutorials/issue_triage/index.md b/doc/tutorials/issue_triage/index.md new file mode 100644 index 00000000000..38e4285c2ce --- /dev/null +++ b/doc/tutorials/issue_triage/index.md @@ -0,0 +1,232 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tutorial: Set up a single project for issue triage **(FREE ALL)** + +<!-- vale gitlab.FutureTense = NO --> + +Issue triage is the process of categorization according to type and severity. +As your project grows and people create more issues, it's worth creating a workflow for how you'll +triage incoming issues. + +In this tutorial, you'll learn how to set up a GitLab project for this. + +To set up GitLab for issue triage in a project: + +1. [Create a project](#create-a-project) +1. [Decide on the criteria for types, severity, and priority](#decide-on-the-criteria-for-types-severity-and-priority) +1. [Document your criteria](#document-your-criteria) +1. [Create scoped labels](#create-scoped-labels) +1. [Prioritize the new labels](#prioritize-the-new-labels) +1. [Create an issue triage board](#create-an-issue-triage-board) +1. [Create issues for features](#create-issues-for-features) + +## Prerequisites + +- If you're using an existing project for this tutorial, make sure you have at least the Reporter role + for the project. +- If you follow the steps below and later decide to create a parent group for your project, to make + best use of labels, you'll have to promote the project labels to group labels. + Consider creating a group first. + +## Create a project + +A project contains the issues that are used for planning your upcoming code changes. + +If you already have a project you're working in, proceed to +[Decide on the criteria for types, severity, and priority](#decide-on-the-criteria-for-types-severity-and-priority). + +To create a blank project: + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Create blank project**. +1. Enter the project details. + - For **Project name**, enter `Issue triage tutorial`. +1. Select **Create project**. + +## Decide on the criteria for types, severity, and priority + +Next, you'll need to determine: + +- **Types** of issues you want to recognize. If you need a more granular approach, you + can also create subtypes for each type. Types help categorize work to get an understanding of the + kind of work that is requested of your team. +- Levels of **priorities** and **severities** to define the impact that incoming work has on end + users and to assist in prioritization. + +For this tutorial, suppose you've decided on the following: + +- Type: `Bug`, `Feature`, and `Maintenance` +- Priority: `1`, `2`, `3`, and `4` +- Severity: `1`, `2`, `3`, and `4` + +For inspiration, see how we define these at GitLab: + +- [Types and subtypes](https://about.gitlab.com/handbook/engineering/metrics/#work-type-classification) +- [Priority](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#priority) +- [Severity](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#severity) + +## Document your criteria + +After you agree on all the criteria, write it all down somewhere your team mates can always access. + +For example, add it to a [wiki](../../user/project/wiki/index.md) in your project, or your company +handbook published with [GitLab Pages](../../user/project/pages/index.md). + +<!-- Idea for expanding this tutorial: + Add steps for [creating a wiki page](../../user/project/wiki/index.md#create-a-new-wiki-page). --> + +## Create scoped labels **(PREMIUM ALL)** + +Next, you'll create labels to add to issues to categorize them. + +The best tool for this is [scoped labels](../../user/project/labels.md#scoped-labels), which you +can use to set mutually exclusive attributes. + +Checking with the list of types, severities, and priorities you've assembled +[previously](#decide-on-the-criteria-for-types-severity-and-priority), you'll want to create matching +scoped labels. + +The double colon (`::`) in the name of a scoped label prevents two labels of the same scope being +used together. +For example, if you add the `type::feature` label to an issue that already has `type::bug`, the +previous one is removed. + +NOTE: +Scoped labels are available in the Premium and Ultimate tier. +If you're on the Free tier, you can use regular labels instead. +However, they aren't mutually exclusive. + +To create each label: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. +1. Select **New label**. +1. In the **Title** field, enter the name of the label. Start with `type::bug`. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color in the **Background color** field. +1. Select **Create label**. + +Repeat these steps to create all the labels you'll need: + +- `type::bug` +- `type::feature` +- `type::maintenance` +- `priority::1` +- `priority::2` +- `priority::3` +- `priority::4` +- `severity::1` +- `severity::2` +- `severity::3` +- `severity::4` + +## Prioritize the new labels + +Now, set the new labels as priority labels, which ensures that the most important issues show on top +of the issue list if you sort by priority or label priority. + +To learn what happens when you sort by priority or label priority, see +[Sorting and ordering issue lists](../../user/project/issues/sorting_issue_lists.md). + +To prioritize a label: + +1. On the Labels page, next to a label you want to prioritize, select the star (**{star-o}**). + This label now appears at the top of the label list, under **Prioritized labels**. +1. To change the relative priority of these labels, drag them up and down the list. + The labels higher in the list get higher priority. +1. Prioritize all the labels you created previously. + Make sure that labels of higher priority and severity are higher on the list than the lower values. + + + +## Create an issue triage board + +To prepare for the incoming issue backlog, create an [issue board](../../user/project/issue_board.md) that organizes issues by label. +You'll use it to quickly create issues and add labels to them by dragging cards to various lists. + +To set up your issue board: + +1. Decide on the scope of the board. For example, create one that you'll use to assign + severity to issues. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your + **Issue triage tutorial** project. +1. Select **Plan > Issue boards**. +1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. +1. Select **Create new board**. +1. In the **Title field**, enter `Issue triage (by severity)`. +1. Keep the **Show the Open list** checkbox selected and clear the **Show the Closed list** one. +1. Select **Create board**. You should see an empty board. +1. Create a list for the `severity::1` label: + 1. In the upper-left corner of the issue board page, select **Create list**. + 1. In the column that appears, from the **Value** dropdown list, select the `severity::1` label. + 1. Select **Add to board**. +1. Repeat the previous step for labels `severity::2`, `severity::3`, and `severity::4`. + +For now, the lists in your board should be empty. Next, you'll populate them with some issues. + +## Create issues for features + +To track upcoming features and bugs, you must create some issues. +Issues belong in projects, but you can also create them directly from your issue board. + +Start by creating some issues for planned features. +You can create issues for bugs as you find them (hopefully not too many!). + +To create an issue from your **Issue triage (by severity)** board: + +1. On the **Open** list, select **Create new issue** (**{plus}**). + The **Open** list shows issues that don't fit any other board list. + + If you already know which severity label your issue should have, you can create it directly from that label list. + Each issue created from a label list will be given that label. +1. Complete the fields: + - Under **Title**, enter `User registration`. +1. Select **Create issue**. +1. Repeat these steps to create a few more issues. + + For example, if you're building an app, create the following issues: + + - `User registration` + - `Profile creation` + - `Search functionality` + - `Add to favorites` + - `Push notifications` + - `Social sharing` + - `In-app messaging` + - `Track progress` + - `Feedback and ratings` + - `Settings and preferences` + +Your first triage issue board is ready! +Try it out by dragging some issues from the **Open** list to one of the label lists to add one of +the severity labels. + + + +## Next steps + +Next, you can: + +- Tweak how you use issue boards. Some options include: + - Edit your current issue board to also have lists for priority and type labels. + This way, you'll make the board wider and might require some horizontal scrolling. + - Create separate issue boards named `Issue triage (by priority)` and `Issue triage (by type)`. + This way, you'll keep various types of triage work separate, but will require switching between + boards. + - [Set up issue boards for team hand-off](../boards_for_teams/index.md). +- Browse issues by priority or severity in issue lists, + [filtered by each label](../../user/project/issues/managing_issues.md#filter-the-list-of-issues). + If it's available to you, make use of + [the "is one of" filter operator](../../user/project/issues/managing_issues.md#filter-with-the-or-operator). +- Break the issues down into [tasks](../../user/tasks.md). +- Create policies that help automate issue triage in a project with the [`gitlab-triage` gem](https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage). + Generate summary reports with heatmaps like the following: + +  + +To learn more about issue triage at GitLab, see [Issue Triage](https://about.gitlab.com/handbook/engineering/quality/issue-triage/) +and [Triage Operations](https://about.gitlab.com/handbook/engineering/quality/triage-operations/). diff --git a/doc/tutorials/learn_git.md b/doc/tutorials/learn_git.md index 6df9b3944b7..afc4ef90ffc 100644 --- a/doc/tutorials/learn_git.md +++ b/doc/tutorials/learn_git.md @@ -13,5 +13,6 @@ the most out of GitLab. |-------|-------------|--------------------| | [Make your first Git commit](make_first_git_commit/index.md) | Create a project, edit a file, and commit changes to a Git repository from the command line. | **{star}** | | [Start using Git on the command line](../gitlab-basics/start-using-git.md) | Learn how to set up Git, clone repositories, and work with branches. | **{star}** | -| [Take advantage of Git rebase](https://about.gitlab.com/blog/2022/10/06/take-advantage-of-git-rebase/)| Learn how to use the `rebase` command in your workflow. | | +| [Take advantage of Git rebase](https://about.gitlab.com/blog/2022/10/06/take-advantage-of-git-rebase/) | Learn how to use the `rebase` command in your workflow. | | +| [Update Git commit messages](update_commit_messages/index.md) | Learn how to update commit messages and push the changes to GitLab. | | | [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF of common Git commands. | | diff --git a/doc/tutorials/left_sidebar/index.md b/doc/tutorials/left_sidebar/index.md index 80fbbf2032e..fee10fbe783 100644 --- a/doc/tutorials/left_sidebar/index.md +++ b/doc/tutorials/left_sidebar/index.md @@ -4,7 +4,7 @@ group: Tutorials info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- -# Tutorial: Use the left sidebar to navigate GitLab **(FREE)** +# Tutorial: Use the left sidebar to navigate GitLab **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9044) in GitLab 16.0. diff --git a/doc/tutorials/make_your_first_git_commit.md b/doc/tutorials/make_your_first_git_commit.md deleted file mode 100644 index 04c66a953af..00000000000 --- a/doc/tutorials/make_your_first_git_commit.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'make_first_git_commit/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](make_first_git_commit/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/move_personal_project_to_a_group.md b/doc/tutorials/move_personal_project_to_a_group.md deleted file mode 100644 index 361181fdde6..00000000000 --- a/doc/tutorials/move_personal_project_to_a_group.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'move_personal_project_to_group/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](move_personal_project_to_group/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/plan_and_track.md b/doc/tutorials/plan_and_track.md index 657ade465b7..7dcafbd26ce 100644 --- a/doc/tutorials/plan_and_track.md +++ b/doc/tutorials/plan_and_track.md @@ -14,6 +14,8 @@ issues, epics, and more. | [GitLab Agile Project Management](https://levelup.gitlab.com/courses/gitlab-agile-project-management) | Learn how to use planning features to manage your projects in this self-paced course. | **{star}** | | [Create a project from a template](https://gitlab.com/projects/new#create_from_template) | Choose a project template and create a project with files to get you started. | | | [Migrate to GitLab](../user/project/import/index.md) | If you are coming to GitLab from another platform, you can import or convert your projects. | | +| [Build a protected workflow for your project](protected_workflow/index.md) | Set up a workflow for your teams, and enforce protections with approval rules. | | | [Run an agile iteration](agile_sprint/index.md) | Use group, projects, and iterations to run an agile development iteration. | +| [Set up a single project for issue triage](issue_triage/index.md) | Use labels to set up a project for issue triage. | **{star}** | | [Set up issue boards for team hand-off](boards_for_teams/index.md) | Use issue boards and scoped labels to set up collaboration across many teams. | **{star}** | | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Epics and Issue Boards](https://www.youtube.com/watch?v=I1bFIAQBHB8) | Find out how to use epics and issue boards for project management. | | diff --git a/doc/tutorials/protected_workflow/index.md b/doc/tutorials/protected_workflow/index.md index 5245bdc5ba9..b055faddc75 100644 --- a/doc/tutorials/protected_workflow/index.md +++ b/doc/tutorials/protected_workflow/index.md @@ -6,7 +6,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated <!-- vale gitlab.FutureTense = NO --> -# Tutorial: Build a protected workflow for your project **(FREE)** +# Tutorial: Build a protected workflow for your project **(FREE ALL)** When your team starts a new project, they need a workflow that balances efficiency with appropriate reviews. In GitLab, you can create user groups, combine those diff --git a/doc/tutorials/scan_result_policy.md b/doc/tutorials/scan_result_policy.md deleted file mode 100644 index 9aacd8eff7b..00000000000 --- a/doc/tutorials/scan_result_policy.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'scan_result_policy/index.md' -remove_date: '2023-07-21' ---- - -This document was moved to [another location](scan_result_policy/index.md). - -<!-- This redirect file can be deleted after 2023-07-21. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/tutorials/scan_result_policy/index.md b/doc/tutorials/scan_result_policy/index.md index 89bd2e099b6..1c23d6a36eb 100644 --- a/doc/tutorials/scan_result_policy/index.md +++ b/doc/tutorials/scan_result_policy/index.md @@ -4,7 +4,7 @@ group: Security Policies info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Set up a scan result policy **(ULTIMATE)** +# Tutorial: Set up a scan result policy **(ULTIMATE ALL)** This tutorial shows you how to create and configure a [scan result policy](../../user/application_security/policies/scan-result-policies.md). These policies can be set to take action based on scan results. For example, in this tutorial, you'll set up a policy that requires approval from two specified users if a vulnerability is detected in a merge request. diff --git a/doc/tutorials/update_commit_messages/index.md b/doc/tutorials/update_commit_messages/index.md new file mode 100644 index 00000000000..f6d92b5c13f --- /dev/null +++ b/doc/tutorials/update_commit_messages/index.md @@ -0,0 +1,209 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +--- + +# Tutorial: How to update Git commit messages **(FREE ALL)** + +Occasionally, after you've made a few commits to your branch, you realize you need +to update one or more commit messages. Perhaps you found a typo, or some automation warned you +that your commit message didn't completely align with a project's +[commit message guidelines](../../development/contributing/merge_request_workflow.md#commit-messages-guidelines). + +Updating the message can be tricky if you don't have much practice with using Git +from the command line interface (CLI). But don't worry, even if you have only ever worked in +the GitLab UI, we'll walk you through the steps to use the CLI. + +This tutorial explains how to rewrite commit messages in both cases: + +- If you work from just the GitLab UI, start at step 1. +- If you already have your repository cloned locally, you can skip to step 2. + +To rewrite any number of commit messages: + +1. [Clone your project's repository to your local machine](#clone-your-repository-to-your-local-machine). +1. [Fetch and check out your branch locally](#fetch-and-check-out-your-branch). +1. [Update the commit messages](#update-the-commit-messages). +1. [Push the changes up to GitLab](#push-the-changes-up-to-gitlab). + +## Prerequisites + +You must have: + +- A GitLab project with a Git branch containing commits that you want to update. +- Git [installed on your local machine](../../topics/git/how_to_install_git/index.md). +- The ability to get to your local machine's command line interface (CLI). In macOS, + you can use Terminal. In Windows, you can use PowerShell. Linux users are probably + already familiar with their system's CLI. +- Familiarity with your system's default editor. This tutorial assumes your editor is Vim, + but any text editor should work. If you are unfamiliar with Vim, step 1 to 2 of + [Getting started with Vim](https://opensource.com/article/19/3/getting-started-vim) + explains all the commands used later in this tutorial. +- Permission to overwrite the commit messages. If you are working with multiple people in the same branch, + you should first verify with them that it's OK to update the commits. Some organizations might + have rules against rewriting commits, as it is considered a destructive change. + +You need to authenticate with GitLab to overwrite the commit messages in the final step. +If your GitLab account uses basic username and password authentication, you must have +[two factor authentication (2FA)](../../user/profile/account/two_factor_authentication.md) +disabled to authenticate from the CLI. Alternatively, you can [use an SSH key to authenticate with GitLab](../../user/ssh.md). + +## Clone your repository to your local machine + +The first thing you need to do is get the repository on your local machine: + +1. In GitLab, on your project's overview page, on the top right, select **Clone**. +1. In the dropdown list, copy the URL for your repository by selecting **{copy-to-clipboard}** next to: + - **Clone with HTTPS** if your GitLab account uses basic username and password authentication. + - **Clone with SSH** if you use SSH to authenticate with GitLab. +1. Now switch to the CLI (Terminal, PowerShell, or similar) on your local machine, and go to + the directory where you want to clone the repository. For example, `/users/my-username/my-projects/`. +1. Run `git clone` and paste the URL you copied earlier, for example: + + ```shell + git clone https://gitlab.com/my-username/my-awesome-project.git + ``` + + This clones the repository into a new directory called `my-awesome-project/`. + +Now your repository is on your computer, ready for your Git CLI commands! + +## Fetch and check out your branch + +Next we need to check out the branch that contains the commits to update. + +1. Assuming you are still at the same place in the CLI as the previous step, + change to your project directory with `cd`: + + ```shell + cd my-awesome-project + ``` + +1. Optional. If you've just cloned the repository, your branch should already be + on your computer too. But if you've previously cloned the repository and skipped + to this step, you might need to fetch your branch with: + + ```shell + git fetch origin my-branch-name + ``` + +1. Now that you know for sure that the branch is on your local system, switch to it: + + ```shell + git checkout my-branch-name + ``` + +1. Verify that it's the correct branch with `git log` and check that the most recent commits + match the commits in your branch on GitLab. To exit the log, use `q`. + +## Update the commit messages + +Now we are ready to update the commit messages: + +1. In GitLab, see how far back in the commit history you need to go: + + - If you already have a merge request open for your branch, you can check the + **Commits** tab and use the total number of commits. + - If you are working from a branch only: + 1. Go to **Code > Commits**. + 1. Select the dropdown list in the top left and find your branch. + 1. Find the oldest commit you want to update, and count how far back that commit is. + For example, if you want to update the second and fourth commit, the count would be 4. + +1. From the CLI, start an interactive rebase, which is the Git process to update commits. + Add the count of commits from the previous step to the end of `HEAD~`, for example: + + ```shell + git rebase -i HEAD~4 + ``` + + In this example, Git selects the four most recent commits in the branch to update. + +1. Git launches a text editor and lists the selected commits. + For example, it should look similar to: + + ```shell + pick a0cea50 Fix broken link + pick bb84712 Update milestone-plan.md + pick ce11fad Add list of maintainers + pick d211d03 update template.md + + # Rebase 1f5ec88..d211d03 onto 1f5ec88 (4 commands) + # + # Commands: + # p, pick <commit> = use commit + # r, reword <commit> = use commit, but edit the commit message + # e, edit <commit> = use commit, but stop for amending + # s, squash <commit> = use commit, but meld into previous commit + # f, fixup [-C | -c] <commit> = like "squash" but keep only the previous + # commit's log message, unless -C is used, in which case + # [and so on...] + ``` + +1. The `pick` command tells Git to use the commits without change. You must change + the command from `pick` to `reword` for the commits you want to update. + Type `i` to enter `INSERT` mode, and then start editing the text. + + For example, to update the text of the second and fourth commits in the sample above, + edit it to look like: + + ```shell + pick a0cea50 Fix broken link + reword bb84712 Update milestone-plan.md + pick ce11fad Add list of maintainers + reword d211d03 update template.md + ``` + +1. Save the edited text. Press <kbd>Escape</kbd> to exit `INSERT` mode, + then type `:wq` and <kbd>Enter</kbd> to save and exit. + +1. Git now goes through each commit one at a time and applies the commands we selected. + Any commits with `pick` are added back to the branch unchanged. When Git reaches a commit + with `reword`, it stops and again opens up the text editor. Now it's time to finally update + the text of the commit message! + + - If you only need a one line commit message, update the text as needed. For example: + + ```plaintext + Update the monthly milestone plan + ``` + + - If the commit message needs a title and a body, separate these with a blank line. For example: + + ```plaintext + Update the monthly milestone plan + + Make the milestone plan clearer by listing the responsibilities + of each maintainer. + ``` + + After you save and exit, Git updates the commit message, and processes the next + commits in order. You should see the message `Successfully rebased and update refs/heads/my-branch-name` + when finished. + +1. Optional. To verify that the commit messages were updated, you can run `git log` + and scroll down to see the commit messages. + +## Push the changes up to GitLab + +Now all that's left is to push these changes up to GitLab: + +1. From the CLI, force push the changes to overwrite what exists in the branch in GitLab. + + ```shell + git push -f origin + ``` + + Your terminal might prompt you for your username and password before overwriting + the commit messages in GitLab. + +1. In your project in GitLab, verify that the commits have been updated: + + - If you already have a merge request open for your branch, check the **Commits** tab. + - If you are working from a branch only: + 1. Go to **Code > Commits**. + 1. Select the dropdown list in the top left and find your branch. + 1. Verify that the relevant commits in the list are now updated. + +Congratulations, you have successfully updated your commit messages and pushed them to GitLab! diff --git a/doc/tutorials/website_project_with_analytics/index.md b/doc/tutorials/website_project_with_analytics/index.md new file mode 100644 index 00000000000..a0a78b68585 --- /dev/null +++ b/doc/tutorials/website_project_with_analytics/index.md @@ -0,0 +1,162 @@ +--- +stage: Plan +group: Optimize +info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Tutorial: Set up an analytics-powered website project **(ULTIMATE ALL)** + +When you work on a complex project (for example, a website), you likely collaborate with other people to build and maintain it. +The way you collaborate and communicate in your team can make or break the project, so you want processes in place that help team members follow and achieve the common goal. +Analytics metrics help you understand how the team is doing, and if you need to adjust processes so you can work better together. +GitLab provides different types of [analytics](../../user/analytics/index.md) insights at the instance, group, and project level. +If this list seems long and you're not sure where to start, then this tutorial is for you. + +Follow along to learn how to set up an example website project, collaborate with other GitLab users, +and use project-level analytics reports to evaluate the development of your project. + +Prerequisite: + +- You must have the Owner role for the group in which you create the project. + +Here's an overview of what we're going to do: + +1. Create a project from a template. +1. Invite users to the project. +1. Create project labels. +1. Create a value stream with a custom stage. +1. Create an Insights report. +1. View merge request and issue analytics. + +## Create a project from a template + +First of all, you need to create a project in your group. + +GitLab provides project templates, +which make it easier to set up a project with all the necessary files for various use cases. +Here, you'll create a project for a Hugo website. + +To create a project: + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Create from template**. +1. Select the **Pages/Hugo** template. +1. In the **Project name** text box, enter a name (for example `My website`). +1. From the **Project URL** dropdown list, select the group you want to create the project in. +1. In the **Project slug** text box, enter a slug for your project (for example, `my-website`). +1. Optional. In the **Project description** text box, enter a description of your project. + For example, "Analytics-powered project for a website built with Hugo". You can add or edit this description at any time. +1. Under **Visibility Level**, select the desired level for the project. + If you create the project in a group, the visibility setting for a project must be at least as restrictive as the visibility of its parent group. +1. Select **Create project**. + +Now you have a project with all the files you need for a Hugo website. + +## Invite users to the project + +When working on a large project such as a website, you'll likely need to collaborate with other people, +such as developers and designers. +You have to invite them to your project, so that they get access to all the files, issues, and reports. + +To invite a user to the `My website` project: + +1. In the project, select **Manage > Members**. +1. Select **Invite members**. +1. Enter the user's **username**. +1. From the **Role** dropdown list, select the **Developer** role or higher. + Users must have at least the Developer role to view analytics and contribute to issues and merge requests. +1. Optional. In the **Access expiration date** picker, select a date. + This step is recommended if the invited member is expected to contribute to the project only for a limited time. +1. Select **Invite**. + +The invited user should now be a member of the project. +You can [view, filter, and search for members](../../user/project/members/index.md#filter-and-sort-members) of your project. + +## Create project labels + +[Labels](../../user/project/labels.md) help you organize and track issues, merge requests, and epics. +You can create as many labels as you need for your projects and groups. +For example, for a website project like this one, the labels `feature request` and `bug` might be useful. + +To create a project label, in the `My website` project: + +1. Select **Manage > Labels**. +1. Select **New label**. +1. In the **Title** field, enter `feature request`. +1. Optional. In the **Description** field, enter additional information about how and when to use this label. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for a specific color in the **Background color** field. +1. Select **Create label**. + +The label should now appear in the [label list](../../user/project/labels.md#view-project-labels), +and you can use it to create a value stream with a custom stage. + +## Create a value stream with a custom stage + +Now that you have a project with collaborators, you can start tracking and visualizing the activity. +[Value Stream Analytics](../../user/group/value_stream_analytics/index.md) helps you measure the time it takes +to go from an idea to production, and identify inefficiencies in the development process. + +To get started, create a value stream in the `My website` project: + +1. Select **Analyze > Value Stream Analytics**. +1. Select **Create new Value Stream**. +1. Enter a name for the value stream, for example `My website value stream`. +1. Select **Create from default template**. +1. To add a custom stage, select **Add another stage**. + - Enter a name for the stage, for example `Labeled MRs merged`. + - From the **Start event** dropdown list, select **Merge request label was added**, then the `feature request` label. + - From the **Stop event** dropdown list, select **Merge request merged**. +1. Select **Create value stream**. + +After you create the value stream, data starts collecting and loading. +This process might take a while. When it's ready, the dashboard is displayed in **Analyze > Value Stream Analytics**. + +In the meantime, you can start creating an Insights report for your project. + +## Create an Insights report + +While Value Stream Analytics give an overview of the entire development process, +[Insights](../../user/project/insights/index.md) provide a more granular view of a project's +issues created and closed, and average merge time of merge requests. +This data visualization can help you triage issues at a glance. + +You can create as many Insights reports with different charts as you need. +For example, a stacked bar chart for bugs by severity or a line chart for issues opened over the month. + +To create an Insights report, in the `My website` project: + +1. Above the file list, select the plus icon, then select **New file**. +1. In the **File name** text box, enter `.gitlab/insights.yml`. +1. In the large text box, enter the following code: + + ```yaml + bugsCharts: + title: "Charts for bugs" + charts: + - title: "Monthly bugs created" + description: "Open bugs created per month" + type: bar + query: + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + group_by: month + period_limit: 12 + ``` + +1. Select **Commit changes**. + +Now you have an Insights bar chart that displays the number of issues with the label `~bug` created per month, for the past 12 months. +You and project members with at least the Developer role can view the Insights report in **Analyze > Insights**. + +## View merge request and issue analytics + +In addition to the Insights reports, you can get detailed analytics on the merge requests and issues of your project. +[Merge request analytics](../../user/analytics/merge_request_analytics.md) and [Issue analytics](../../user/analytics/issue_analytics.md) display charts and tables with metrics such as assignees, merge request throughput, and issue status. + +To view merge request and issue analytics, in the `My website` project, select **Analyze > Merge request analytics** or **Analyze > Issue analytics**. + +That was it! Now you have an analytics-powered website project on which you can collaborate efficiently with your team. |
