diff options
Diffstat (limited to 'doc/tutorials')
36 files changed, 1606 insertions, 563 deletions
diff --git a/doc/tutorials/agile_sprint.md b/doc/tutorials/agile_sprint.md index ff0b17d7eb0..84927fe0a66 100644 --- a/doc/tutorials/agile_sprint.md +++ b/doc/tutorials/agile_sprint.md @@ -1,101 +1,11 @@ --- -stage: none -group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +redirect_to: 'agile_sprint/index.md' +remove_date: '2023-07-21' --- -# Tutorial: Use GitLab to run an Agile iteration +This document was moved to [another location](agile_sprint/index.md). -To run an Agile development iteration in GitLab, you use multiple GitLab features -that work together. - -To run an Agile iteration from GitLab: - -1. Create a group. -1. Create a project. -1. Set up an iteration cadence. -1. Create scoped labels. -1. Create your epics and issues. -1. Create an issue board. - -After you've created these core components, you can begin running your iterations. - -## Create a group - -Iteration cadences are created at the group level, so start by -[creating one](../user/group/manage.md#create-a-group) if you don't have one already. - -You use groups to manage one or more related projects at the same time. -You add your users as members in the group, and assign them a role. Roles determine -the [level of permissions](../user/permissions.md) each user has on the projects in the group. -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. -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. - -## Set up an iteration cadence - -Before you start creating epics or issues, create an -[iteration cadence](../user/group/iterations/index.md#iteration-cadences). -Iteration cadences contain the individual, sequential iteration timeboxes for planning and reporting -on your issues. - -When creating an iteration cadence, you can decide whether to automatically manage the iterations or -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. - -```mermaid -graph TD - Group --> SubgroupA --> Project1 - Group --> SubgroupB --> Project2 - Group --> IterationCadence -``` - -## Create scoped labels - -You should also [create scoped labels](../user/project/labels.md) in the same group where you created -your iteration cadence. Labels help you -organize your epics, issues, and merge requests, as well as help you -to visualize the flow of issues in boards. For example, you can use scoped labels like -`workflow::planning`, `workflow::ready for development`, `workflow::in development`, and `workflow::complete` -to indicate the status of an issue. You can also leverage scoped labels to denote the type of issue -or epic such as `type::feature`, `type::defect`, and `type::maintenance`. - -## Create your epics and issues - -Now you can get started planning your iterations. Start by creating [epics](../user/group/epics/index.md) -in the group where you created your iteration cadence, -then create child [issues](../user/project/issues/index.md) in one or more of your projects. -Add labels to each as needed. - -## Create an issue board - -[Issue boards](../user/project/issue_board.md) help you plan your upcoming iterations or visualize -the workflow of the iteration currently in progress. List columns can be created based on label, -assignee, iteration, or milestone. You can also filter the board by multiple attributes and group -issues by their epic. - -In the group where you created your iteration cadence and labels, -[create an issue board](../user/project/issue_board.md#create-an-issue-board) and name it -"Iteration Planning." Then, create lists for each of your iterations. You can then drag issues from -the "Open" list into iteration lists to schedule them for upcoming iterations. - -To visualize the workflow for issues in the current iteration, create another issue board called -"Current Iteration." When you're creating the board: - -1. Select **Edit board**. -1. Next to **Iteration**, select **Edit**. -1. From the dropdown list, select **Current iteration**. -1. Select **Save changes**. - -Your board will now only ever show issues that are in the current iteration. -You can start adding lists for each of the `workflow::...` labels you created previously. - -Now you're ready to start development. +<!-- 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 new file mode 100644 index 00000000000..0ce100df65e --- /dev/null +++ b/doc/tutorials/agile_sprint/index.md @@ -0,0 +1,101 @@ +--- +stage: none +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 GitLab to run an Agile iteration + +To run an Agile development iteration in GitLab, you use multiple GitLab features +that work together. + +To run an Agile iteration from GitLab: + +1. Create a group. +1. Create a project. +1. Set up an iteration cadence. +1. Create scoped labels. +1. Create your epics and issues. +1. Create an issue board. + +After you've created these core components, you can begin running your iterations. + +## Create a group + +Iteration cadences are created at the group level, so start by +[creating one](../../user/group/manage.md#create-a-group) if you don't have one already. + +You use groups to manage one or more related projects at the same time. +You add your users as members in the group, and assign them a role. Roles determine +the [level of permissions](../../user/permissions.md) each user has on the projects in the group. +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. +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. + +## Set up an iteration cadence + +Before you start creating epics or issues, create an +[iteration cadence](../../user/group/iterations/index.md#iteration-cadences). +Iteration cadences contain the individual, sequential iteration timeboxes for planning and reporting +on your issues. + +When creating an iteration cadence, you can decide whether to automatically manage the iterations or +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. + +```mermaid +graph TD + Group --> SubgroupA --> Project1 + Group --> SubgroupB --> Project2 + Group --> IterationCadence +``` + +## Create scoped labels + +You should also [create scoped labels](../../user/project/labels.md) in the same group where you created +your iteration cadence. Labels help you +organize your epics, issues, and merge requests, as well as help you +to visualize the flow of issues in boards. For example, you can use scoped labels like +`workflow::planning`, `workflow::ready for development`, `workflow::in development`, and `workflow::complete` +to indicate the status of an issue. You can also leverage scoped labels to denote the type of issue +or epic such as `type::feature`, `type::defect`, and `type::maintenance`. + +## Create your epics and issues + +Now you can get started planning your iterations. Start by creating [epics](../../user/group/epics/index.md) +in the group where you created your iteration cadence, +then create child [issues](../../user/project/issues/index.md) in one or more of your projects. +Add labels to each as needed. + +## Create an issue board + +[Issue boards](../../user/project/issue_board.md) help you plan your upcoming iterations or visualize +the workflow of the iteration currently in progress. List columns can be created based on label, +assignee, iteration, or milestone. You can also filter the board by multiple attributes and group +issues by their epic. + +In the group where you created your iteration cadence and labels, +[create an issue board](../../user/project/issue_board.md#create-an-issue-board) and name it +"Iteration Planning." Then, create lists for each of your iterations. You can then drag issues from +the "Open" list into iteration lists to schedule them for upcoming iterations. + +To visualize the workflow for issues in the current iteration, create another issue board called +"Current Iteration." When you're creating the board: + +1. Select **Edit board**. +1. Next to **Iteration**, select **Edit**. +1. From the dropdown list, select **Current iteration**. +1. Select **Save changes**. + +Your board will now only ever show issues that are in the current iteration. +You can start adding lists for each of the `workflow::...` labels you created previously. + +Now you're ready to start development. diff --git a/doc/tutorials/boards_for_teams/index.md b/doc/tutorials/boards_for_teams/index.md new file mode 100644 index 00000000000..e37bf5a2d31 --- /dev/null +++ b/doc/tutorials/boards_for_teams/index.md @@ -0,0 +1,202 @@ +--- +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 issue boards for team hand-off **(PREMIUM)** + +<!-- vale gitlab.FutureTense = NO --> + +This tutorial shows you how to set up [issue boards](../../user/project/issue_board.md) and [scoped labels](../../user/project/labels.md#scoped-labels) for two teams that work on issues in sequence. + +In this example, you'll create two issue boards for the UX and Frontend teams. +Using the following steps, you can create issue boards and workflows for more sub-teams, like Backend +or Quality Assurance. +To learn how we use workflow labels at GitLab, see [Product Development Flow](https://about.gitlab.com/handbook/product-development-flow). + +To set up issue boards for multiple teams: + +1. [Create a group](#create-a-group) +1. [Create a project](#create-a-project) +1. [Create labels](#create-labels) +1. [Create team issue boards](#create-team-issue-boards) +1. [Create issues for features](#create-issues-for-features) + +## The goal workflow + +After you set up everything, the two teams will be able to hand off issues from one board to another, for example, like this: + +1. The project lead adds the `Workflow::Ready for design` and `Frontend` labels to a feature issue called **Redesign user profile page**. +1. A product designer on the UX team: + 1. Checks the `Workflow::Ready for design` list on the **UX workflow** board and decides to work on the profile page redesign. + + <!-- Image: UX board with lists: + ~Workflow::Ready for design, + ~Workflow::Design + ~Workflow::Ready for development --> + + 1. Assigns themselves to the issue. + 1. Drags the issue card to the `Workflow::Design` list. The previous workflow label is automatically removed. + 1. Creates the ✨new designs✨. + 1. [Adds the designs to the issue](../../user/project/issues/design_management.md). + 1. Drags the issue card to the `Workflow::Ready for development` list, which adds this label and removes any other `Workflow::` label. + 1. Unassigns themselves from the issue. +1. A developer on the Frontend team: + 1. Checks the `Workflow::Ready for development` list on the **Frontend workflow** board and chooses an issue to work on. + + <!-- Image: Frontend board, scoped to ~Frontend, with lists: + ~Workflow::Ready for development + ~Workflow::In development + ~Workflow::Complete --> + + 1. Assigns themselves to the issue. + 1. Drags the issue card to the `Workflow::In development` list. The previous workflow label is automatically removed. + 1. Adds the frontend code in a [merge request](../../user/project/merge_requests/index.md). + 1. Adds the `Workflow::Complete` label. + +## Create a group + +To prepare for when your project grows, start by creating a group. +You use groups to manage one or more related projects at the same time. +You add your users as members in the group, and assign them a role. + +Prerequisites: + +- If you're using an existing group for this tutorial, make sure you have at least the Reporter role + for the group. + +To create a group: + +1. On the top bar, select **Create new... > New group**. +1. Select **Create group**. +1. Complete the fields. Name your group `Paperclip Software Factory`. +1. Select **Create group**. + +You've created an empty group. Next, you'll create a project that will store your issues and code. + +## Create a project + +The main code development work happens in projects and their repositories. +A project contains your code and pipelines, but also the issues that are used for planning your +upcoming code changes. + +Prerequisites: + +- If you're using an existing project for this tutorial, make sure you have at least the Reporter role + for the project. + +To create a blank project: + +1. In your group, on the right of the page, select **New project**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, name your project `Paperclip Assistant`. +1. Select **Create project**. + +## Create labels + +You need a team label and a set of workflow labels to show where in the development cycle an issue is. + +You could create these labels in your `Paperclip Assistant` project, but it's better to create them +in the `Paperclip Software Factory` group. This way, these labels will also be available in all the other +projects you create later. + +To create each label: + +1. On the top bar, select **Main menu > Group** and find your **Paperclip Software Factory** group. +1. On the left sidebar, select **Group information > Labels**. +1. Select **New label**. +1. In the **Title** field, enter the name of the label. Start with `Frontend`. +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: + +- `Frontend` +- `Workflow::Ready for design` +- `Workflow::Design` +- `Workflow::Ready for development` +- `Workflow::In development` +- `Workflow::Complete` + +## Create team issue boards + +Like with labels, you could create your issue boards in the **Paperclip Assistant** project, +but it can be better to have them in the **Paperclip Software Factory** group. This way, you'll be able +to manage issues from all the projects that you might create later in this group. + +To create a new group issue board: + +1. On the top bar, select **Main menu > Group** and find your **Paperclip Software Factory** group. +1. On the left sidebar, select **Issues > Boards**. +1. Create the UX workflow and Frontend workflow boards. + +To create the **UX workflow** issue board: + +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 `UX workflow`. +1. Clear the **Show the Open list** and **Show the Closed list** checkboxes. +1. Select **Create board**. You should see an empty board. + + <!-- Image: empty UX workflow board --> + +1. Create a list for the `Workflow::Ready for design` 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 `Workflow::Ready for design` label. + 1. Select **Add to board**. +1. Repeat the previous step for labels `Workflow::Design` and `Workflow::Ready for development`. + +To create the **Frontend workflow** board: + +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 `Frontend workflow`. +1. Clear the **Show the Open list** and **Show the Closed list** checkboxes. +1. Expand **Scope**. +1. Next to **Labels**, select **Edit** and select the `Frontend` label. +1. Select **Create board**. +1. Create a list for the `Workflow::Ready for development` label: + 1. In the upper-left corner of the issue board page, select **Create list**. + 1. In the column that appeared, from the **Value** dropdown list, select the `Workflow::Ready for development` label. + 1. Select **Add to board**. +1. Repeat the previous step for labels `Workflow::In development` and `Workflow::Complete`. + +For now, lists in both your boards should be empty. Next, you'll populate them with some issues. + +## Create issues for features + +To track upcoming features, enhancements, and bugs, you must create some issues. +Issues belong in projects, but you can also create them directly from your issue board. + +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. Complete the fields: + 1. Under **Title**, enter `Redesign user profile page`. + 1. Under **Projects**, select **Paperclip Software Factory / Paperclip Assistant**. +1. Select **Create issue**. Because you created the new issue in the label list, it gets created + with this label. +1. Add the `Frontend` label, because only issues with this label appear on the Frontend team's board: + 1. Select the issue card (not its title), and a sidebar appears on the right. + 1. In the **Labels** section of the sidebar, select **Edit**. + 1. From the **Assign labels** dropdown list, select the `Workflow::Ready for design` and + `Frontend` labels. The selected labels are marked with a checkmark. + 1. To apply your changes to labels, select **X** next to **Assign labels** or select any area + outside the label section. + +Repeat these steps to create a few more issues with the same labels. + +You should now see at least one issue there, ready for your product designers to start working on! + +<!-- Image: UX workflow board with at least one issue in the `Workflow::Ready for design` list --> + +Congratulations! Now your teams can start collaborating on amazing software. + +## Learn more about project management in GitLab + +Find other tutorials about project management on the [tutorials page](../plan_and_track.md). diff --git a/doc/tutorials/build_application.md b/doc/tutorials/build_application.md new file mode 100644 index 00000000000..2e0130e46ca --- /dev/null +++ b/doc/tutorials/build_application.md @@ -0,0 +1,32 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Build your application + +## Learn about CI/CD pipelines + +Use CI/CD pipelines to automatically build, test, and deploy your code. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Create and run your first GitLab CI/CD pipeline](../ci/quick_start/index.md) | Create a `.gitlab-ci.yml` file and start a pipeline. | **{star}** | +| [Create a complex pipeline](../ci/quick_start/tutorial.md) | Learn about the most commonly used GitLab CI/CD keywords by building an increasingly complex pipeline. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Get started: Learn about CI/CD](https://www.youtube.com/watch?v=sIegJaLy2ug) (9m 02s) | Learn about the `.gitlab-ci.yml` file and how it's used. | **{star}** | +| [GitLab CI/CD](https://levelup.gitlab.com/courses/continuous-integration-and-delivery-ci-cd-with-gitlab) | Learn about GitLab CI/CD and build a pipeline in this self-paced course. | **{star}** | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [CI deep dive](https://www.youtube.com/watch?v=ZVUbmVac-m8&list=PL05JrBw4t0KorkxIFgZGnzzxjZRCGROt_&index=27) (22m 51s) | Take a closer look at pipelines and continuous integration concepts. | | +| [Set up CI/CD in the cloud](../ci/examples/index.md#cicd-in-the-cloud) | Learn how to set up CI/CD in different cloud-based environments. | | +| [Find CI/CD examples and templates](../ci/examples/index.md#cicd-examples) | Use these examples and templates to set up CI/CD for your use case. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Understand CI/CD rules](https://www.youtube.com/watch?v=QjQc-zeL16Q) (8m 56s) | Learn more about how to use CI/CD rules. | | +| [Use Auto DevOps to deploy an application](../topics/autodevops/cloud_deployments/auto_devops_with_gke.md) | Deploy an application to Google Kubernetes Engine (GKE). | | + +## Publish a static website + +Use GitLab Pages to publish a static website directly from your project. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [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. | | diff --git a/doc/tutorials/compliance_pipeline/index.md b/doc/tutorials/compliance_pipeline/index.md new file mode 100644 index 00000000000..2dab7a7ecb1 --- /dev/null +++ b/doc/tutorials/compliance_pipeline/index.md @@ -0,0 +1,177 @@ +--- +stage: Govern +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)** + +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 +to projects through [compliance frameworks](../../user/group/compliance_frameworks.md). + +In this tutorial, you: + +1. Create a [new group](#create-a-new-group). +1. Create a [new project for the compliance pipeline configuration](#create-a-new-compliance-pipeline-project). +1. Configure a [compliance framework](#configure-compliance-framework) to apply to other projects. +1. Create a [new project and apply the compliance framework](#create-a-new-project-and-apply-the-compliance-framework) to it. +1. Combine [compliance pipeline configuration and regular pipeline configuration](#combine-pipeline-configurations). + +Prerequisites: + +- Permission to create new top-level groups. + +## Create a new group + +Compliance frameworks are configured in top-level groups. In this tutorial, you create a top-level group that: + +- Contains two projects: + - The compliance pipeline project to store the compliance pipeline configuration. + - Another project that must run a job in its pipeline that is defined by the compliance pipeline configuration. +- Has the compliance framework to apply to projects. + +To create the new group: + +1. On the top bar, select **Create new... > New group**. +1. Select **Create group**. +1. In the **Group name** field, enter `Tutorial group`. +1. Select **Create group**. + +## Create a new compliance pipeline project + +Now you're ready to create a compliance pipeline project. This project contains the +[compliance pipeline configuration](../../user/group/compliance_frameworks.md#example-configuration) to apply to all +projects with the compliance framework applied. + +To create the compliance pipeline project: + +1. On the top bar, select **Main menu > Groups** and find the `Tutorial group` group. +1. Select **New project**. +1. Select **Create blank project**. +1. In the **Project name** field, enter `Tutorial compliance project`. +1. Select **Create project**. + +To add compliance pipeline configuration to `Tutorial compliance project`: + +1. On the top bar, select **Main menu > Projects** and find the `Tutorial compliance project` project. +1. On the left sidebar, select **CI/CD > Editor**. +1. Select **Configure pipeline**. +1. In the pipeline editor, replace the default configuration with: + + ```yaml + --- + compliance-job: + script: + - echo "Running compliance job required for every project in this group..." + ``` + +1. Select **Commit changes**. + +## Configure compliance framework + +The compliance framework is configured in the [new group](#create-a-new-group). + +To configure the compliance framework: + +1. On the top bar, select **Main menu > Groups** and find the `Tutorial group` group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Compliance frameworks**. +1. Select **Add framework**. +1. In the **Name** field, enter `Tutorial compliance framework`. +1. In the **Description** field, enter `Compliance framework for tutorial`. +1. In the **Compliance pipeline configuration (optional)** field, enter + `.gitlab-ci.yml@tutorial-group/tutorial-compliance-project`. +1. In the **Background color** field, select a color of your choice. +1. Select **Add framework**. + +For convenience, make the new compliance framework the default for all new projects in the group: + +1. On the top bar, select **Main menu > Groups** and find the `Tutorial group` group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Compliance frameworks**. +1. In the row for `Tutorial compliance framework`, select **Options** (**{ellipsis_v}**). +1. Select **Set default**. + +## Create a new project and apply the compliance framework + +Your compliance framework is ready, so you can now create projects in the group and they automatically run the +compliance pipeline configuration in their pipelines. + +To create a new project for running the compliance pipeline configuration: + +1. On the top bar, select **Main menu > Groups** and find the `Tutorial group` group. +1. Select **New project**. +1. Select **Create blank project**. +1. In the **Project name** field, enter `Tutorial project`. +1. Select **Create project**. + +On the project page, notice the `Tutorial compliance framework` label appears because that was set as the default +compliance framework for the group. + +Without any other pipeline configuration, `Tutorial project` can run the jobs defined in the compliance +pipeline configuration in `Tutorial compliance project`. + +To run the compliance pipeline configuration in `Tutorial project`: + +1. On the top bar, select **Main menu > Projects** and find the `Tutorial project` project. +1. Select **CI/CD Pipelines**. +1. Select **Run pipeline**. +1. On the **Run pipeline** page, select **Run pipeline**. + +Notice the pipeline runs a job called `compliance-job` in a **test** stage. Nice work, you've run your first compliance +job! + +## Combine pipeline configurations + +If you want projects to run their own jobs as well as the compliance pipeline jobs, you must combine the compliance +pipeline configuration and the regular pipeline configuration of the project. + +To combine the pipeline configurations, you must define the regular pipeline configuration and then update the +compliance pipeline configuration to refer to it. + +To create the regular pipeline configuration: + +1. On the top bar, select **Main menu > Projects** and find the `Tutorial project` project. +1. On the left sidebar, select **CI/CD > Editor**. +1. Select **Configure pipeline**. +1. In the pipeline editor, replace the default configuration with: + + ```yaml + --- + project-job: + script: + - echo "Running project job..." + ``` + +1. Select **Commit changes**. + +To combine the new project pipeline configuration with the compliance pipeline configuration: + +1. On the top bar, select **Main menu > Projects** and find the `Tutorial compliance project` project. +1. On the left sidebar, select **CI/CD > Editor**. +1. In the existing configuration, add: + + ```yaml + include: + - project: 'tutorial-group/tutorial-project' + file: '.gitlab-ci.yml' + ``` + +1. Select **Commit changes**. + +To confirm the regular pipeline configuration is combined with the compliance pipeline configuration: + +1. On the top bar, select **Main menu > Projects** and find the `Tutorial project` project. +1. Select **CI/CD Pipelines**. +1. Select **Run pipeline**. +1. On the **Run pipeline** page, select **Run pipeline**. + +Notice the pipeline runs two jobs in a **test** stage: + +- `compliance-job`. +- `project-job`. + +Congratulations, you've created and configured a compliance pipeline! + +See more [example compliance pipeline configurations](../../user/group/compliance_frameworks.md#example-configuration). diff --git a/doc/tutorials/convert_personal_namespace_into_group.md b/doc/tutorials/convert_personal_namespace_into_group.md new file mode 100644 index 00000000000..c1b3b58efb8 --- /dev/null +++ b/doc/tutorials/convert_personal_namespace_into_group.md @@ -0,0 +1,11 @@ +--- +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/convert_personal_namespace_to_group/index.md b/doc/tutorials/convert_personal_namespace_to_group/index.md new file mode 100644 index 00000000000..53ad46effd9 --- /dev/null +++ b/doc/tutorials/convert_personal_namespace_to_group/index.md @@ -0,0 +1,95 @@ +--- +stage: Data Stores +group: Tenant Scale +info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Tutorial: Convert a personal namespace into a group **(FREE SAAS)** + +If you've started out on GitLab with a personal [namespace](../../user/namespace/index.md), but now find +that you've outgrown its capabilities and its limitations hinder the collaboration on your projects, +you might want to switch to a group namespace instead. +A group namespace allows you to create multiple subgroups, and manage their members and permissions. + +You don't have to start from scratch - you can create a new group +and move your existing projects to the group to get the added benefits. +To find out how, see [Tutorial: Move your personal project to a group](../move_personal_project_to_group/index.md). + +But you can go one step further and convert your personal namespace into a group namespace, +so you get to keep the existing username and URL. For example, if your username is `alex`, +you can continue using the `https://gitlab.example.com/alex` URL for your group. + +This tutorial shows you how to convert your personal namespace into a group namespace +using the following steps: + +1. [Create a group](#create-a-group). +1. [Transfer projects from the personal namespace to the group](#transfer-projects-from-the-personal-namespace-to-the-group). +1. [Rename the original username](#rename-the-original-username). +1. [Rename the new group namespace to the original username](#rename-the-new-group-namespace-to-the-original-username). + +For example, if your username for a personal namespace is `alex`, first create a group namespace named `alex-group`. +Then, move all projects from the `alex` to the `alex-group` namespace. Finally, +rename the `alex` namespace to `alex-user`, and `alex-group` namespace to the now available `alex` username. + +## Create a group + +1. On the top bar, select **Main menu > Groups > View all groups**. +1. On the right of the page, select **New group**. +1. In **Group name**, enter a name for the group. +1. In **Group URL**, enter a path for the group, which is used as the namespace. + Don't worry about the actual path, this is only temporary. You'll change this URL to the username of the personal namespace in the [final step](#rename-the-new-group-namespace-to-the-original-username). +1. Choose the [visibility level](../../user/public_access.md). +1. Optional. Fill in information to personalize your experience. +1. Select **Create group**. + +## Transfer projects from the personal namespace to the group + +Next, you must transfer your projects from the personal namespace to the new group. +You can transfer only one project at a time, so if you want to transfer multiple projects, +you must perform the steps below for each project. + +Before you start the transfer process, make sure you: + +- Have the Owner role for the project. +- Remove [container images](../../user/packages/container_registry/index.md#move-or-rename-container-registry-repositories). + You can't transfer a project that contains container images. +- Remove npm packages. You can't update the root namespace of a project that contains npm packages. + +To transfer a project to a group: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. Under **Transfer project**, choose the group to transfer the project to. +1. Select **Transfer project**. +1. Enter the project's name and select **Confirm**. + +## Rename the original username + +Next, rename the original username of the personal namespace, so that the username becomes available for the new group namespace. +You can keep on using the personal namespace for other personal projects, or [delete that user account](../../user/profile/account/delete_account.md) + +From the moment you rename the personal namespace, the username becomes available, so it's possible that someone else registers an account with it. To avoid this, you should [rename the new group](#rename-the-new-group-namespace-to-the-original-username) as soon as possible. + +To [change a user's username](../../user/profile/index.md#change-your-username): + +1. On the top bar, in the top-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Account**. +1. In the **Change username** section, enter a new username as the path. +1. Select **Update username**. + +## Rename the new group namespace to the original username + +Finally, rename the new group's URL to the username of the original personal namespace. + +To [change your group path](../../user/group/manage.md#change-a-groups-path) (group URL): + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General page**. +1. Expand the **Advanced** section. +1. Under **Change group URL**, enter the user's original username. +1. Select **Change group URL**. + +That's it! You have now converted a personal namespace into a group, which opens up new possibilities of +working on projects and collaborating with more members. diff --git a/doc/tutorials/create_compliance_pipeline.md b/doc/tutorials/create_compliance_pipeline.md new file mode 100644 index 00000000000..ac5550ad6a4 --- /dev/null +++ b/doc/tutorials/create_compliance_pipeline.md @@ -0,0 +1,11 @@ +--- +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/develop.md b/doc/tutorials/develop.md new file mode 100644 index 00000000000..08497a09830 --- /dev/null +++ b/doc/tutorials/develop.md @@ -0,0 +1,17 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Develop with GitLab + +## Integrate with GitLab + +GitLab [integrates](../user/project/integrations/index.md) with a number of third-party services, +enabling you to work with those services directly from GitLab. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Integrate with Jira](https://about.gitlab.com/blog/2021/04/12/gitlab-jira-integration-selfmanaged/) | Configure the Jira integration, so you can work with Jira issues from GitLab. | | +| [Integrate with Gitpod](https://about.gitlab.com/blog/2021/07/19/teams-gitpod-integration-gitlab-speed-up-development/) | Integrate with Gitpod, to help speed up your development. | | diff --git a/doc/tutorials/fuzz_testing/index.md b/doc/tutorials/fuzz_testing/index.md new file mode 100644 index 00000000000..1d4985f9003 --- /dev/null +++ b/doc/tutorials/fuzz_testing/index.md @@ -0,0 +1,243 @@ +--- +stage: Secure +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)** + +[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. + +This helps you discover bugs and potential security issues that other QA processes may miss. + +You should use fuzz testing in addition to other security scanners and your own test processes. +If you're using GitLab CI/CD, you can run fuzz tests as part your CI/CD workflow. + +To set up, configure, and perform coverage-guided fuzz testing +using JavaScript in this tutorial, you: + +1. [Fork the project template](#fork-the-project-template) to create a project + to run the fuzz tests in. +1. [Create the fuzz targets](#create-the-fuzz-targets). +1. [Enable coverage-guided fuzz testing](#enable-coverage-guided-fuzz-testing) + in your forked project. +1. [Run the fuzz test](#run-the-fuzz-test) to identify security vulnerabilities. +1. [Fix any vulnerabilities](#fix-the-vulnerabilities) identified by the fuzz test. + +## Fork the project template + +First, to create a project to try out fuzz testing in, you must fork the `fuzz-testing` +project template: + +1. Open the [`fuzz-testing` project template](https://gitlab.com/gitlab-org/tutorial-project-templates/fuzz-testing). +1. [Fork the project template](../../user/project/repository/forking_workflow.md). +1. When forking the project template: + - Name the forked project `fuzz-testing-demo`. + - Select an appropriate [namespace](../../user/namespace/index.md). + - Set [project visibility](../../user/public_access.md) to **Private**. + +You have successfully forked the `fuzz-testing` project template. Before you can +start fuzz testing, remove the relationship between the project template and the fork: + +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the **Remove fork relationship** section, select **Remove fork relationship**. + Enter the name of the project when prompted. + +Your project is ready and you can now create the fuzz test. Next you will create +the fuzz targets. + +## Create the fuzz targets + +Now you have a project for fuzz testing, you create the fuzz targets. A fuzz target +is a function or program that, given an input, makes a call to the application +being tested. + +In this tutorial, the fuzz targets call a function of the `my-tools.js` file using +a random buffer as a parameter. + +To create the two fuzz target files: + +1. On the top bar, select **Main menu > Projects** and select the `fuzz-testing-demo` project. +1. Create a file in the root directory of the project. +1. Name the file `fuzz-sayhello.js` and add the following code: + + ```javascript + let tools = require('./my-tools') + + function fuzz(buf) { + const text = buf.toString() + tools.sayHello(text) + } + + module.exports = { + fuzz + } + ``` + + You can also copy this code from the `fuzz-testing-demo/fuzzers/fuzz-sayhello.js` + project file. + +1. Name the **Target Branch** `add-fuzz-test` and write a descriptive commit message. + - Do not select the **Start a new merge request with these changes** checkbox yet. +1. Select **Commit changes**. +1. Return to the root directory of the project. +1. Make sure you are in the `add-fuzz-test` branch. +1. Create the second file named `fuzz-readme.js` and add the following code: + + ```javascript + let tools = require('./my-tools') + function fuzz(buf) { + const text = buf.toString() + tools.readmeContent(text) + } + module.exports = { + fuzz + } + ``` + + You can also copy this code from the `fuzz-testing-demo/fuzzers/fuzz-readme.js` + project file. + +1. Write a descriptive commit message. +1. Make sure the **Target Branch** is `add-fuzz-test`. +1. Select **Commit changes**. + +You now have two fuzz targets that can make calls to the application being tested. +Next you will enable the fuzz testing. + +## Enable coverage-guided fuzz testing + +To enable coverage-guided fuzz testing, create a CI/CD pipeline running +the `gitlab-cov-fuzz` CLI to execute the fuzz test on the two fuzz targets. + +To create the pipeline file: + +1. Make sure you are in the `add-fuzz-test` branch. +1. In the root directory of the `fuzz-testing-demo` project, create a new file. +1. Name the file `.gitlab-ci.yml` and add the following code: + + ```yaml + image: node:18 + + stages: + - fuzz + + include: + - template: Coverage-Fuzzing.gitlab-ci.yml + + readme_fuzz_target: + extends: .fuzz_base + tags: [saas-linux-large-amd64] # Optional + variables: + COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' + script: + - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz + - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-readme.js + + hello_fuzzing_target: + extends: .fuzz_base + tags: [saas-linux-large-amd64] # Optional + variables: + COVFUZZ_ADDITIONAL_ARGS: '--fuzzTime=60' + script: + - npm config set @gitlab-org:registry https://gitlab.com/api/v4/packages/npm/ && npm i -g @gitlab-org/jsfuzz + - ./gitlab-cov-fuzz run --engine jsfuzz -- fuzz-sayhello.js + ``` + + This step adds the following to your pipeline: + - A `fuzz` stage using a template. + - Two jobs, `readme_fuzz_target` and `hello_fuzzing_target`. Each job runs using + the `jsfuzz` engine, which reports unhandled exceptions as crashes. + + You can also copy this code from the `fuzz-testing-demo/fuzzers/fuzzers.yml` + project file. + +1. Write a descriptive commit message. +1. Make sure the **Target Branch** is `add-fuzz-test`. +1. Select **Commit changes**. + +You have successfully enabled coverage-guided fuzz testing. Next you will run the +fuzz test using the pipeline you've just created. + +## Run the fuzz test + +To run the fuzz test: + +1. On the left sidebar, select **Merge requests**. +1. Select **New merge request**. +1. In the **Source branch** section, select the `add-fuzz-test` branch. +1. In the **Target branch** section, make sure that your namespace and the `main` branch are selected. +1. Select **Compare branches and continue**. +1. [Create the merge request](../../user/project/merge_requests/creating_merge_requests.md). + +Creating the merge request triggers a new pipeline, which runs the fuzz test. +When the pipeline is finished running, you should see a security vulnerability +alert on the merge request page. + +To see more information on each vulnerability, select the individual **Uncaught-exception** links. + +You have successfully run the fuzz test and identified vulnerabilities to fix. + +## Fix the vulnerabilities + +The fuzz test identified two security vulnerabilities. To fix those +vulnerabilities, you use the `my-tools.js` library. + +To create the `my-tools.js` file: + +1. Make sure you are in the `add-fuzz-test` branch of the project. +1. Go to the root directory of your project and open the `my-tools.js` file. +1. Replace the contents of this file with the following code: + + ```javascript + const fs = require('fs') + + function sayHello(name) { + if(name.includes("z")) { + //throw new Error("😡 error name: " + name) + console.log("😡 error name: " + name) + } else { + return "😀 hello " + name + } + } + + function readmeContent(name) { + + let fileName = name => { + if(name.includes("w")) { + return "./README.txt" + } else { + return "./README.md" + } + } + + //const data = fs.readFileSync(fileName(name), 'utf8') + try { + const data = fs.readFileSync(fileName(name), 'utf8') + return data + } catch (err) { + console.error(err.message) + return "" + } + + } + + module.exports = { + sayHello, readmeContent + } + ``` + + You can also copy the code from the `fuzz-testing-demo/javascript/my-tools.js` + project file. + +1. Select **Commit changes**. This triggers another pipeline to run another fuzz test. +1. When the pipeline is finished, check the merge request **Overview** page. You + should see that the security scan detected no new potential vulnerabilities. +1. Merge your changes. + +Congratulations, you've successfully run a fuzz test and fixed the identified +security vulnerabilities! + +For more information, see [coverage-guided fuzz testing](../../user/application_security/coverage_fuzzing/index.md). diff --git a/doc/tutorials/fuzz_testing_tutorial.md b/doc/tutorials/fuzz_testing_tutorial.md new file mode 100644 index 00000000000..74b24005077 --- /dev/null +++ b/doc/tutorials/fuzz_testing_tutorial.md @@ -0,0 +1,11 @@ +--- +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/gitlab_navigation.md b/doc/tutorials/gitlab_navigation.md new file mode 100644 index 00000000000..6003fbf67c0 --- /dev/null +++ b/doc/tutorials/gitlab_navigation.md @@ -0,0 +1,21 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Find your way around GitLab + +Get to know the features of GitLab and where to find them so you can get up +and running quickly. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Introduction to GitLab](https://youtu.be/_4SmIyQ5eis?t=90) (59m 51s) | Walk through recommended processes and example workflows for using GitLab. | **{star}** | +| [GitLab with Git Essentials](https://levelup.gitlab.com/courses/gitlab-with-git-essentials) | Learn the basics of Git and GitLab in this self-paced course. | **{star}** | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Use GitLab for DevOps](https://www.youtube.com/watch?v=7q9Y1Cv-ib0) (12m 34s) | Use GitLab through the entire DevOps lifecycle, from planning to monitoring. | **{star}** | +| [Use the left sidebar to navigate GitLab](left_sidebar/index.md) | Start navigating the GitLab UI. | **{star}** | +| [Use Markdown at GitLab](../user/markdown.md) | GitLab Flavored Markdown (GLFM) is used in many areas of GitLab, for example, in merge requests. | **{star}** | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Learn GitLab project walkthrough](https://www.youtube.com/watch?v=-oaI2WEKdI4&list=PL05JrBw4t0KofkHq4GZJ05FnNGa11PQ4d) (59m 2s) | Step through the tutorial-style issues in the **Learn GitLab** project. If you don't have this project, download [the export file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/project_templates/learn_gitlab_ultimate.tar.gz) and [import it to a new project](../user/project/settings/import_export.md#import-a-project-and-its-data). | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GitLab Continuous Delivery overview](https://www.youtube.com/watch?v=g-gO93PMZvk&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=134) (17m 2s) | Learn how to use GitLab features to continuously build, test, and deploy iterative code changes. | | +| [Productivity tips](https://about.gitlab.com/blog/2021/02/18/improve-your-gitlab-productivity-with-these-10-tips/) | Get tips to help make you a productive GitLab user. | | diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md index c1b538bafbe..b06cd224d0c 100644 --- a/doc/tutorials/index.md +++ b/doc/tutorials/index.md @@ -8,117 +8,11 @@ info: For assistance with this tutorials page, see https://about.gitlab.com/hand These tutorials can help you learn how to use GitLab. -## Find your way around GitLab - -Get to know the features of GitLab and where to find them so you can get up -and running quickly. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Introduction to GitLab](https://youtu.be/_4SmIyQ5eis?t=90) (59m 51s) | Walk through recommended processes and example workflows for using GitLab. | **{star}** | -| [GitLab 101](https://levelup.gitlab.com/learn/course/gitlab101) | Learn the basics of GitLab in this certification course. | **{star}** | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Use GitLab for DevOps](https://www.youtube.com/watch?v=7q9Y1Cv-ib0) (12m 34s) | Use GitLab through the entire DevOps lifecycle, from planning to monitoring. | **{star}** | -| [Use Markdown at GitLab](../user/markdown.md) | GitLab Flavored Markdown (GLFM) is used in many areas of GitLab, for example, in merge requests. | **{star}** | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Learn GitLab project walkthrough](https://www.youtube.com/watch?v=-oaI2WEKdI4&list=PL05JrBw4t0KofkHq4GZJ05FnNGa11PQ4d) (59m 2s) | Step through the tutorial-style issues in the **Learn GitLab** project. If you don't have this project, download [the export file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/project_templates/learn_gitlab_ultimate.tar.gz) and [import it to a new project](../user/project/settings/import_export.md#import-a-project-and-its-data). | | -| [Productivity tips](https://about.gitlab.com/blog/2021/02/18/improve-your-gitlab-productivity-with-these-10-tips/) | Get tips to help make you a productive GitLab user. | | - -## Use Git - -GitLab is a Git-based platform, so understanding Git is important to get -the most out of GitLab. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [Make your first Git commit](make_your_first_git_commit.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. | | -| [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF of common Git commands. | | - -## Plan your work in projects - -Your work takes place in a project, from creating code, to planning, -collaborating, and more. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [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. | | -| [Run an agile iteration](agile_sprint.md) | Use group, projects, and iterations to run an agile development iteration. | - -## Use CI/CD pipelines - -CI/CD pipelines are used to automatically build, test, and deploy your code. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [Create and run your first GitLab CI/CD pipeline](../ci/quick_start/index.md) | Create a `.gitlab-ci.yml` file and start a pipeline. | **{star}** | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Get started: Learn about CI/CD](https://www.youtube.com/watch?v=sIegJaLy2ug) (9m 02s) | Learn about the `.gitlab-ci.yml` file and how it's used. | **{star}** | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [CI deep dive](https://www.youtube.com/watch?v=ZVUbmVac-m8&list=PL05JrBw4t0KorkxIFgZGnzzxjZRCGROt_&index=27) (22m 51s) | Take a closer look at pipelines and continuous integration concepts. | | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [CD deep dive](https://www.youtube.com/watch?v=Cn0rzND-Yjw&list=PL05JrBw4t0KorkxIFgZGnzzxjZRCGROt_&index=10) (47m 54s) | Learn about deploying in GitLab. | | -| [Set up CI/CD in the cloud](../ci/examples/index.md#cicd-in-the-cloud) | Learn how to set up CI/CD in different cloud-based environments. | | -| [Find CI/CD examples and templates](../ci/examples/index.md#cicd-examples) | Use these examples and templates to set up CI/CD for your use case. | | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Understand CI/CD rules](https://www.youtube.com/watch?v=QjQc-zeL16Q) (8m 56s) | Learn more about how to use CI/CD rules. | | - -## Configure your applications and infrastructure - -Use GitLab configuration features to reduce the effort needed to -configure the infrastructure for your application. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [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. | | -| [Use Auto DevOps to deploy an application](../topics/autodevops/cloud_deployments/auto_devops_with_gke.md) | Deploy an application to Google Kubernetes Engine (GKE). | | - -## Publish a static website - -Use GitLab Pages to publish a static website directly from your project. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [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. | | - -## Secure your application - -GitLab can check your application for security vulnerabilities. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [Set up dependency scanning](https://about.gitlab.com/blog/2021/01/14/try-dependency-scanning/) | Try out dependency scanning, which checks for known vulnerabilities in dependencies. | **{star}** | -| [Get started with GitLab application security](../user/application_security/get-started-security.md) | Follow recommended steps to set up security tools. | | - -## Work with a self-managed instance - -If you're an administrator of a self-managed instance of GitLab, these tutorials -can help you manage and configure your instance. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [Install GitLab](../install/install_methods.md) | Install GitLab according to your requirements.| | -| [Get started administering GitLab](../administration/get_started.md) | Configure your organization and its authentication, then secure, monitor, and back up GitLab. | | - -## Integrate with GitLab - -GitLab [integrates](../user/project/integrations/index.md) with a number of third-party services, -enabling you to work with those services directly from GitLab. - -| Topic | Description | Good for beginners | -|-------|-------------|--------------------| -| [Integrate with Jira](https://about.gitlab.com/blog/2021/04/12/gitlab-jira-integration-selfmanaged/) | Configure the Jira integration, so you can work with Jira issues from GitLab. | | -| [Integrate with Gitpod](https://about.gitlab.com/blog/2021/07/19/teams-gitpod-integration-gitlab-speed-up-development/) | Integrate with Gitpod, to help speed up your development. | | - -## Find more tutorial content - -If you're learning about GitLab, here are some ways you can find more tutorial -content: - -- Find learning tracks and certification options at [GitLab Learn](https://about.gitlab.com/learn/). - GitLab learning platform login required (email and password for non-GitLab team members). - -- Find recent tutorials on the GitLab blog by [searching by the `tutorial` tag](https://about.gitlab.com/blog/tags.html#tutorial). - -- Browse the **Learn@GitLab** [playlist on YouTube](https://www.youtube.com/playlist?list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED) - to find video tutorials. - -If you find an article, video, or other resource that would be a -great addition to this page, add it in a [merge request](../development/documentation/index.md). +- [Find your way around GitLab](gitlab_navigation.md) +- [Learn Git](learn_git.md) +- [Plan and track your work](plan_and_track.md) +- [Build your application](build_application.md) +- [Secure your application and check compliance](secure_application.md) +- [Manage your infrastructure](infrastructure.md) +- [Develop with GitLab](develop.md) +- [Find more tutorials](more_tutorials.md) diff --git a/doc/tutorials/infrastructure.md b/doc/tutorials/infrastructure.md new file mode 100644 index 00000000000..e9035461596 --- /dev/null +++ b/doc/tutorials/infrastructure.md @@ -0,0 +1,15 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Manage your infrastructure + +Use GitLab configuration features to reduce the effort needed to +configure the infrastructure for your application. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [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. | | diff --git a/doc/tutorials/learn_git.md b/doc/tutorials/learn_git.md new file mode 100644 index 00000000000..a5b52ef73e9 --- /dev/null +++ b/doc/tutorials/learn_git.md @@ -0,0 +1,17 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Learn Git + +GitLab is a Git-based platform, so understanding Git is important to get +the most out of GitLab. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [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. | | +| [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/img/admin_area_v16_0.png b/doc/tutorials/left_sidebar/img/admin_area_v16_0.png Binary files differnew file mode 100644 index 00000000000..7cc4ddedea0 --- /dev/null +++ b/doc/tutorials/left_sidebar/img/admin_area_v16_0.png diff --git a/doc/tutorials/left_sidebar/img/explore_v16_0.png b/doc/tutorials/left_sidebar/img/explore_v16_0.png Binary files differnew file mode 100644 index 00000000000..3cbe94e5de4 --- /dev/null +++ b/doc/tutorials/left_sidebar/img/explore_v16_0.png diff --git a/doc/tutorials/left_sidebar/img/pin_v16_0.png b/doc/tutorials/left_sidebar/img/pin_v16_0.png Binary files differnew file mode 100644 index 00000000000..17dbcac4caf --- /dev/null +++ b/doc/tutorials/left_sidebar/img/pin_v16_0.png diff --git a/doc/tutorials/left_sidebar/img/pinned_v16_0.png b/doc/tutorials/left_sidebar/img/pinned_v16_0.png Binary files differnew file mode 100644 index 00000000000..1c8d0bdd2cd --- /dev/null +++ b/doc/tutorials/left_sidebar/img/pinned_v16_0.png diff --git a/doc/tutorials/left_sidebar/img/project_selected_v16_0.png b/doc/tutorials/left_sidebar/img/project_selected_v16_0.png Binary files differnew file mode 100644 index 00000000000..534b06ac5de --- /dev/null +++ b/doc/tutorials/left_sidebar/img/project_selected_v16_0.png diff --git a/doc/tutorials/left_sidebar/img/search_projects_v16_0.png b/doc/tutorials/left_sidebar/img/search_projects_v16_0.png Binary files differnew file mode 100644 index 00000000000..12182f24009 --- /dev/null +++ b/doc/tutorials/left_sidebar/img/search_projects_v16_0.png diff --git a/doc/tutorials/left_sidebar/img/shortcuts_v16_0.png b/doc/tutorials/left_sidebar/img/shortcuts_v16_0.png Binary files differnew file mode 100644 index 00000000000..07094898117 --- /dev/null +++ b/doc/tutorials/left_sidebar/img/shortcuts_v16_0.png diff --git a/doc/tutorials/left_sidebar/img/your_work_v16_0.png b/doc/tutorials/left_sidebar/img/your_work_v16_0.png Binary files differnew file mode 100644 index 00000000000..f7b5ed4217d --- /dev/null +++ b/doc/tutorials/left_sidebar/img/your_work_v16_0.png diff --git a/doc/tutorials/left_sidebar/index.md b/doc/tutorials/left_sidebar/index.md new file mode 100644 index 00000000000..7de50afbe77 --- /dev/null +++ b/doc/tutorials/left_sidebar/index.md @@ -0,0 +1,73 @@ +--- +stage: none +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)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9044) in GitLab 16.0. + +Follow this tutorial to learn how to use the new left sidebar to navigate the UI. + +Provide feedback in +[issue 409005](https://gitlab.com/gitlab-org/gitlab/-/issues/409005). + +## Enable the new left sidebar + +To view the new sidebar: + +1. On the top bar, in the upper-right corner, select your avatar. +1. Turn on the **New navigation** toggle. + +To turn off this sidebar, return to your avatar and turn off the toggle. + +## Find your project + +Let's get started exploring the GitLab UI and left sidebar. + +1. Start by finding the project you want to work on. + To explore all available projects, on the left sidebar, select **Explore**: + +  + +1. On the right, above the list of projects, type search criteria. + The search finds projects with a matching description. + +  + +1. When you find the project you want, select the project name. + The left sidebar now shows project-specific options. + +  + +Your issues, merge requests, and to-do items are listed in the shortcuts +at the top: + + + +## Customize the sidebar + +You can pin menu items if you tend to use them frequently. + +1. Expand the sections until you are viewing the item you want to pin. +1. Hover over and select the pin (**{thumbtack}**). + +  + +The item is displayed in the **Pinned** section: + + + +## Use a more focused view + +On the left sidebar, you can also choose a more focused view into the areas you have access to. +Change the view to **Your work**: + + + +## Go to the Admin Area + +The Admin Area is also available on the left sidebar: + + diff --git a/doc/tutorials/img/branches_dropdown_v14_10.png b/doc/tutorials/make_first_git_commit/img/branches_dropdown_v14_10.png Binary files differindex 926baff0ff8..926baff0ff8 100644 --- a/doc/tutorials/img/branches_dropdown_v14_10.png +++ b/doc/tutorials/make_first_git_commit/img/branches_dropdown_v14_10.png diff --git a/doc/tutorials/img/clone_project_v14_9.png b/doc/tutorials/make_first_git_commit/img/clone_project_v14_9.png Binary files differindex 98666c95ba3..98666c95ba3 100644 --- a/doc/tutorials/img/clone_project_v14_9.png +++ b/doc/tutorials/make_first_git_commit/img/clone_project_v14_9.png diff --git a/doc/tutorials/img/commit_message_v14_10.png b/doc/tutorials/make_first_git_commit/img/commit_message_v14_10.png Binary files differindex 5636a135b4e..5636a135b4e 100644 --- a/doc/tutorials/img/commit_message_v14_10.png +++ b/doc/tutorials/make_first_git_commit/img/commit_message_v14_10.png diff --git a/doc/tutorials/make_first_git_commit/index.md b/doc/tutorials/make_first_git_commit/index.md new file mode 100644 index 00000000000..794b9d1f4b5 --- /dev/null +++ b/doc/tutorials/make_first_git_commit/index.md @@ -0,0 +1,271 @@ +--- +stage: none +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: Make your first Git commit + +This tutorial is going to teach you a little bit about how Git works. It walks +you through the steps of creating your own project, editing a file, and +committing changes to a Git repository from the command line. + +When you're done, you'll have a project where you can practice using Git. + +## What you need + +Before you begin: + +- [Install Git on your local machine](../../topics/git/how_to_install_git/index.md). +- Ensure you can sign in to an instance of GitLab. If your organization doesn't + have GitLab, create an account on GitLab.com. +- [Create SSH keys and add them to GitLab](../../user/ssh.md). SSH keys are how you + securely communicate between your computer and GitLab. + +## What is Git? + +Before we jump into steps, let's go over some basic Git concepts. + +Git is a version control system. It's used to track changes to files. + +You store files, like code or documents, in a Git *repository*. When you want to edit the files, you +*clone* the repository to your computer, make the changes, and *push* your changes +back to the repository. In GitLab, a Git repository is located in +a *project*. + +Each time you push a change, Git records it as a unique *commit*. These commits make up +the history of when and how a file changed, and who changed it. + +```mermaid +graph LR + subgraph Repository commit history + direction LR + A(Author: Alex<br>Date: 3 Jan at 1PM<br>Commit message: Added sales figures<br> Commit ID: 123abc12) ---> B + B(Author: Sam<br>Date: 4 Jan at 10AM<br>Commit message: Removed old info<br> Commit ID: aabb1122) ---> C + C(Author: Zhang<br>Date: 5 Jan at 3PM<br>Commit message: Added invoices<br> Commit ID: ddee4455) + end +``` + +When you work in a Git repository, you work in *branches*. By default, the contents +of a repository are in a default branch. To make changes, you: + +1. Create your own branch, which is a snapshot of the default branch at the time + you create it. +1. Make changes and push them to your branch. Each push creates a commit. +1. When you're ready, *merge* your branch into the default branch. + +```mermaid +flowchart LR + subgraph Default branch + A[Commit] --> B[Commit] --> C[Commit] --> D[Commit] + end + subgraph My branch + B --1. Create my branch--> E(Commit) + E --2. Add my commit--> F(Commit) + F --3. Merge my branch to default--> D + end +``` + +If this all feels a bit overwhelming, hang in there. You're about to see these concepts in action. + +## Steps + +Here's an overview of what we're going to do: + +1. [Create a sample project](#create-a-sample-project). +1. [Clone the repository](#clone-the-repository). +1. [Create a branch and make your changes](#create-a-branch-and-make-changes). +1. [Commit and push your changes](#commit-and-push-your-changes). +1. [Merge your changes](#merge-your-changes). +1. [View your changes in GitLab](#view-your-changes-in-gitlab). + +### Create a sample project + +To start, create a sample project in GitLab. + +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. For **Project name**, enter `My sample project`. The project slug is generated for you. + This slug is the URL you can use to access the project after it's created. +1. Ensure **Initialize repository with a README** is selected. + How you complete the other fields is up to you. +1. Select **Create project**. + +### Clone the repository + +Now you can clone the repository in your project. *Cloning* a repository means you're creating +a copy on your computer, or wherever you want to store and work with the files. + +1. On your project page, select **Clone**. Copy the URL for **Clone with SSH**. + +  + +1. Open a terminal on your computer and go to the directory + where you want to clone the files. + +1. Enter `git clone` and paste the URL: + + ```shell + git clone git@gitlab.com:gitlab-example/my-sample-project.git + ``` + +1. Go to the directory: + + ```shell + cd my-sample-project + ``` + +1. By default, you've cloned the default branch for the repository. Usually this + branch is `main`. To be sure, get the name of the default branch: + + ```shell + git branch + ``` + + The branch you're on is marked with an asterisk. + Press `Q` on your keyboard to return to the main terminal + window. + +### Create a branch and make changes + +Now that you have a copy of the repository, create your own branch so you can +work on your changes independently. + +1. Create a new branch called `example-tutorial-branch`. + + ```shell + git checkout -b example-tutorial-branch + ``` + +1. In a text editor like Visual Studio Code, Sublime, `vi`, or any other editor, + open the README.md file and add this text: + + ```plaintext + Hello world! I'm using Git! + ``` + +1. Save the file. + +1. Git keeps track of changed files. To confirm which files have changed, get + the status. + + ```shell + git status + ``` + + You should get output similar to the following: + + ```shell + On branch example-tutorial-branch + Changes not staged for commit: + (use "git add <file>..." to update what will be committed) + (use "git restore <file>..." to discard changes in working directory) + modified: README.md + + no changes added to commit (use "git add" and/or "git commit -a") + ``` + +### Commit and push your changes + +You've made changes to a file in your repository. Now it's time to record +those changes by making your first commit. + +1. Add the `README.md` file to the *staging* area. The staging area is where you + put files before you commit them. + + ```shell + git add README.md + ``` + +1. Confirm the file is staged: + + ```shell + git status + ``` + + You should get output similar to the following, and the filename should be in + green text. + + ```shell + On branch example-tutorial-branch + Changes to be committed: + (use "git restore --staged <file>..." to unstage) + modified: README.md + ``` + +1. Now commit the staged file, and include a message + that describes the change you made. Make sure you surround the message in double + quotes ("). + + ```shell + git commit -m "I added text to the README file" + ``` + +1. The change has been committed to your branch, but your branch and its commits + are still only available on your computer. No one else has access to them yet. + Push your branch to GitLab: + + ```shell + git push origin example-tutorial-branch + ``` + +Your branch is now available on GitLab and visible to other users in your project. + + + +### Merge your changes + +Now you're ready to merge the changes from your `example-tutorial-branch` branch +to the default branch (`main`). + +1. Check out the default branch for your repository. + + ```shell + git checkout main + ``` + +1. Merge your branch into the default branch. + + ```shell + git merge example-tutorial-branch + ``` + +1. Push the changes. + + ```shell + git push + ``` + +NOTE: +For this tutorial, you merge your branch directly to the default branch for your +repository. In GitLab, you typically use a [merge request](../../user/project/merge_requests/index.md) +to merge your branch. + +### View your changes in GitLab + +You did it! You updated the `README.md` file in your branch, and you merged those changes +into the `main` branch. + +Let's look in the UI and confirm your changes. Go to your project. + +- Scroll down and view the contents of the `README.md` file. + Your changes should be visible. +- Above the `README.md` file, view the text in the **Last commit** column. + Your commit message is displayed in this column: + +  + +Now you can return to the command line and change back to your personal branch +(`git checkout example-tutorial-branch`). You can continue updating files or +creating new ones. Type `git status` to view the status +of your changes and commit with abandon. + +Don't worry if you mess things up. Everything in Git can be reverted, and if you +find you can't recover, you can always create a new branch and start again. + +Nice work. + +## Find more Git learning resources + +- Get a complete introduction to Git in the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Git for GitLab](https://www.youtube.com/watch?v=4lxvVj7wlZw) beginner's course (1h 33m). +- Find other tutorials about Git and GitLab on the [tutorials page](../index.md). diff --git a/doc/tutorials/make_your_first_git_commit.md b/doc/tutorials/make_your_first_git_commit.md index 3df65389c76..04c66a953af 100644 --- a/doc/tutorials/make_your_first_git_commit.md +++ b/doc/tutorials/make_your_first_git_commit.md @@ -1,271 +1,11 @@ --- -stage: none -group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +redirect_to: 'make_first_git_commit/index.md' +remove_date: '2023-07-21' --- -# Tutorial: Make your first Git commit +This document was moved to [another location](make_first_git_commit/index.md). -This tutorial is going to teach you a little bit about how Git works. It walks -you through the steps of creating your own project, editing a file, and -committing changes to a Git repository from the command line. - -When you're done, you'll have a project where you can practice using Git. - -## What you need - -Before you begin: - -- [Install Git on your local machine](../topics/git/how_to_install_git/index.md). -- Ensure you can sign in to an instance of GitLab. If your organization doesn't - have GitLab, create an account on GitLab.com. -- [Create SSH keys and add them to GitLab](../user/ssh.md). SSH keys are how you - securely communicate between your computer and GitLab. - -## What is Git? - -Before we jump into steps, let's go over some basic Git concepts. - -Git is a version control system. It's used to track changes to files. - -You store files, like code or documents, in a Git *repository*. When you want to edit the files, you -*clone* the repository to your computer, make the changes, and *push* your changes -back to the repository. In GitLab, a Git repository is located in -a *project*. - -Each time you push a change, Git records it as a unique *commit*. These commits make up -the history of when and how a file changed, and who changed it. - -```mermaid -graph LR - subgraph Repository commit history - direction LR - A(Author: Alex<br>Date: 3 Jan at 1PM<br>Commit message: Added sales figures<br> Commit ID: 123abc12) ---> B - B(Author: Sam<br>Date: 4 Jan at 10AM<br>Commit message: Removed old info<br> Commit ID: aabb1122) ---> C - C(Author: Zhang<br>Date: 5 Jan at 3PM<br>Commit message: Added invoices<br> Commit ID: ddee4455) - end -``` - -When you work in a Git repository, you work in *branches*. By default, the contents -of a repository are in a default branch. To make changes, you: - -1. Create your own branch, which is a snapshot of the default branch at the time - you create it. -1. Make changes and push them to your branch. Each push creates a commit. -1. When you're ready, *merge* your branch into the default branch. - -```mermaid -flowchart LR - subgraph Default branch - A[Commit] --> B[Commit] --> C[Commit] --> D[Commit] - end - subgraph My branch - B --1. Create my branch--> E(Commit) - E --2. Add my commit--> F(Commit) - F --3. Merge my branch to default--> D - end -``` - -If this all feels a bit overwhelming, hang in there. You're about to see these concepts in action. - -## Steps - -Here's an overview of what we're going to do: - -1. [Create a sample project](#create-a-sample-project). -1. [Clone the repository](#clone-the-repository). -1. [Create a branch and make your changes](#create-a-branch-and-make-changes). -1. [Commit and push your changes](#commit-and-push-your-changes). -1. [Merge your changes](#merge-your-changes). -1. [View your changes in GitLab](#view-your-changes-in-gitlab). - -### Create a sample project - -To start, create a sample project in GitLab. - -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. For **Project name**, enter `My sample project`. The project slug is generated for you. - This slug is the URL you can use to access the project after it's created. -1. Ensure **Initialize repository with a README** is selected. - How you complete the other fields is up to you. -1. Select **Create project**. - -### Clone the repository - -Now you can clone the repository in your project. *Cloning* a repository means you're creating -a copy on your computer, or wherever you want to store and work with the files. - -1. On your project page, select **Clone**. Copy the URL for **Clone with SSH**. - -  - -1. Open a terminal on your computer and go to the directory - where you want to clone the files. - -1. Enter `git clone` and paste the URL: - - ```shell - git clone git@gitlab.com:gitlab-example/my-sample-project.git - ``` - -1. Go to the directory: - - ```shell - cd my-sample-project - ``` - -1. By default, you've cloned the default branch for the repository. Usually this - branch is `main`. To be sure, get the name of the default branch: - - ```shell - git branch - ``` - - The branch you're on is marked with an asterisk. - Press `Q` on your keyboard to return to the main terminal - window. - -### Create a branch and make changes - -Now that you have a copy of the repository, create your own branch so you can -work on your changes independently. - -1. Create a new branch called `example-tutorial-branch`. - - ```shell - git checkout -b example-tutorial-branch - ``` - -1. In a text editor like Visual Studio Code, Sublime, `vi`, or any other editor, - open the README.md file and add this text: - - ```plaintext - Hello world! I'm using Git! - ``` - -1. Save the file. - -1. Git keeps track of changed files. To confirm which files have changed, get - the status. - - ```shell - git status - ``` - - You should get output similar to the following: - - ```shell - On branch example-tutorial-branch - Changes not staged for commit: - (use "git add <file>..." to update what will be committed) - (use "git restore <file>..." to discard changes in working directory) - modified: README.md - - no changes added to commit (use "git add" and/or "git commit -a") - ``` - -### Commit and push your changes - -You've made changes to a file in your repository. Now it's time to record -those changes by making your first commit. - -1. Add the `README.md` file to the *staging* area. The staging area is where you - put files before you commit them. - - ```shell - git add README.md - ``` - -1. Confirm the file is staged: - - ```shell - git status - ``` - - You should get output similar to the following, and the filename should be in - green text. - - ```shell - On branch example-tutorial-branch - Changes to be committed: - (use "git restore --staged <file>..." to unstage) - modified: README.md - ``` - -1. Now commit the staged file, and include a message - that describes the change you made. Make sure you surround the message in double - quotes ("). - - ```shell - git commit -m "I added text to the README file" - ``` - -1. The change has been committed to your branch, but your branch and its commits - are still only available on your computer. No one else has access to them yet. - Push your branch to GitLab: - - ```shell - git push origin example-tutorial-branch - ``` - -Your branch is now available on GitLab and visible to other users in your project. - - - -### Merge your changes - -Now you're ready to merge the changes from your `example-tutorial-branch` branch -to the default branch (`main`). - -1. Check out the default branch for your repository. - - ```shell - git checkout main - ``` - -1. Merge your branch into the default branch. - - ```shell - git merge example-tutorial-branch - ``` - -1. Push the changes. - - ```shell - git push - ``` - -NOTE: -For this tutorial, you merge your branch directly to the default branch for your -repository. In GitLab, you typically use a [merge request](../user/project/merge_requests/index.md) -to merge your branch. - -### View your changes in GitLab - -You did it! You updated the `README.md` file in your branch, and you merged those changes -into the `main` branch. - -Let's look in the UI and confirm your changes. Go to your project. - -- Scroll down and view the contents of the `README.md` file. - Your changes should be visible. -- Above the `README.md` file, view the text in the **Last commit** column. - Your commit message is displayed in this column: - -  - -Now you can return to the command line and change back to your personal branch -(`git checkout example-tutorial-branch`). You can continue updating files or -creating new ones. Type `git status` to view the status -of your changes and commit with abandon. - -Don't worry if you mess things up. Everything in Git can be reverted, and if you -find you can't recover, you can always create a new branch and start again. - -Nice work. - -## Find more Git learning resources - -- Get a complete introduction to Git in the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Git for GitLab](https://www.youtube.com/watch?v=4lxvVj7wlZw) beginner's course (1h 33m). -- Find other tutorials about Git and GitLab on the [tutorials page](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/more_tutorials.md b/doc/tutorials/more_tutorials.md new file mode 100644 index 00000000000..c52de180bff --- /dev/null +++ b/doc/tutorials/more_tutorials.md @@ -0,0 +1,20 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Find more tutorial content + +If you're learning about GitLab, to find more tutorial content: + +- Find learning tracks and certification options at [Level Up](https://levelup.gitlab.com/). + GitLab learning platform login required (email and password for non-GitLab team members). + +- Find recent tutorials on the GitLab blog by [searching by the `tutorial` tag](https://about.gitlab.com/blog/tags.html#tutorial). + +- Browse the **Learn@GitLab** [playlist on YouTube](https://www.youtube.com/playlist?list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED) + to find video tutorials. + +If you find an article, video, or other resource that would be a +great addition to this page, add it in a [merge request](../development/documentation/index.md). diff --git a/doc/tutorials/move_personal_project_to_a_group.md b/doc/tutorials/move_personal_project_to_a_group.md index e3ab1e8fbd8..361181fdde6 100644 --- a/doc/tutorials/move_personal_project_to_a_group.md +++ b/doc/tutorials/move_personal_project_to_a_group.md @@ -1,89 +1,11 @@ --- -stage: none -group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +redirect_to: 'move_personal_project_to_group/index.md' +remove_date: '2023-07-21' --- -# Tutorial: Move your personal project to a group **(FREE SAAS)** +This document was moved to [another location](move_personal_project_to_group/index.md). -If you created a project under a [personal namespace](../user/namespace/index.md), -you can perform common tasks, like managing issue and merge requests, -and using source control and CI/CD. - -However, at some point you might outgrow your personal project and -want to move your project to a group namespace instead. With a group namespace, you can: - -- Give a group of users access to your project, rather than adding users one-by-one. -- View all issues and merge requests for all projects in the group. -- View all unique users in the group namespace, across all projects. -- Manage usage quotas. -- Start a trial or upgrade to a paid subscription tier. This option is important if you're - impacted by the [changes to user limits](https://about.gitlab.com/blog/2022/03/24/efficient-free-tier/), - and need more users. - -This tutorial shows you how to move your project from a personal namespace -to a group namespace. - -## Steps - -Here's an overview of the steps: - -1. [Create a group](#create-a-group). -1. [Move your project to a group](#move-your-project-to-a-group). -1. [Work with your group](#work-with-your-group). - -### Create a group - -To begin, make sure you have a suitable group to move your project to. -The group must allow the creation of projects, and you must have at least the -Maintainer role for the group. - -If you don't have a group, create one: - -1. On the top bar, select **Main menu > Groups > View all groups**. -1. On the right of the page, select **New group**. -1. In **Group name**, enter a name for the group. -1. In **Group URL**, enter a path for the group, which is used as the namespace. -1. Choose the [visibility level](../user/public_access.md). -1. Optional. Fill in information to personalize your experience. -1. Select **Create group**. - -### Move your project to a group - -Before you move your project to a group: - -- You must have the Owner role for the project. -- Remove any [container images](../user/packages/container_registry/index.md#move-or-rename-container-registry-repositories) -- Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. - -Now you're ready to move your project: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Advanced**. -1. Under **Transfer project**, choose the group to transfer the project to. -1. Select **Transfer project**. -1. Enter the project's name and select **Confirm**. - -You are redirected to the project's new page. -If you have more than one personal project, you can repeat these steps for each -project. - -NOTE: -For more information about these migration steps, -see [Transferring your project into another namespace](../user/project/settings/index.md#transfer-a-project-to-another-namespace). -A migration might result in follow-up work to update the project path in -your related resources and tools, such as websites and package managers. - -### Work with your group - -You can now view your project in your group: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. Look for your project under **Subgroups and projects**. - -Start enjoying the benefits of a group! For example, as the group Owner, you can -quickly view all unique users in your namespace: - -1. In your group, select **Settings > Usage Quotas**. -1. The **Seats** tab displays all users across all projects in your group. +<!-- 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_group/index.md b/doc/tutorials/move_personal_project_to_group/index.md new file mode 100644 index 00000000000..d3e695b78df --- /dev/null +++ b/doc/tutorials/move_personal_project_to_group/index.md @@ -0,0 +1,89 @@ +--- +stage: Data Stores +group: Tenant Scale +info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Tutorial: Move your personal project to a group **(FREE SAAS)** + +If you created a project under a [personal namespace](../../user/namespace/index.md), +you can perform common tasks, like managing issue and merge requests, +and using source control and CI/CD. + +However, at some point you might outgrow your personal project and +want to move your project to a group namespace instead. With a group namespace, you can: + +- Give a group of users access to your project, rather than adding users one-by-one. +- View all issues and merge requests for all projects in the group. +- View all unique users in the group namespace, across all projects. +- Manage usage quotas. +- Start a trial or upgrade to a paid subscription tier. This option is important if you're + impacted by the [changes to user limits](https://about.gitlab.com/blog/2022/03/24/efficient-free-tier/), + and need more users. + +This tutorial shows you how to move your project from a personal namespace +to a group namespace. + +## Steps + +Here's an overview of the steps: + +1. [Create a group](#create-a-group). +1. [Move your project to a group](#move-your-project-to-a-group). +1. [Work with your group](#work-with-your-group). + +### Create a group + +To begin, make sure you have a suitable group to move your project to. +The group must allow the creation of projects, and you must have at least the +Maintainer role for the group. + +If you don't have a group, create one: + +1. On the top bar, select **Main menu > Groups > View all groups**. +1. On the right of the page, select **New group**. +1. In **Group name**, enter a name for the group. +1. In **Group URL**, enter a path for the group, which is used as the namespace. +1. Choose the [visibility level](../../user/public_access.md). +1. Optional. Fill in information to personalize your experience. +1. Select **Create group**. + +### Move your project to a group + +Before you move your project to a group: + +- You must have the Owner role for the project. +- Remove any [container images](../../user/packages/container_registry/index.md#move-or-rename-container-registry-repositories) +- Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. + +Now you're ready to move your project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. Under **Transfer project**, choose the group to transfer the project to. +1. Select **Transfer project**. +1. Enter the project's name and select **Confirm**. + +You are redirected to the project's new page. +If you have more than one personal project, you can repeat these steps for each +project. + +NOTE: +For more information about these migration steps, +see [Transferring your project into another namespace](../../user/project/settings/index.md#transfer-a-project-to-another-namespace). +A migration might result in follow-up work to update the project path in +your related resources and tools, such as websites and package managers. + +### Work with your group + +You can now view your project in your group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. Look for your project under **Subgroups and projects**. + +Start enjoying the benefits of a group! For example, as the group Owner, you can +quickly view all unique users in your namespace: + +1. In your group, select **Settings > Usage Quotas**. +1. The **Seats** tab displays all users across all projects in your group. diff --git a/doc/tutorials/plan_and_track.md b/doc/tutorials/plan_and_track.md new file mode 100644 index 00000000000..35b552cdaa5 --- /dev/null +++ b/doc/tutorials/plan_and_track.md @@ -0,0 +1,18 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Plan and track your work + +Create a project to host your code, and plan your work using +issues, epics, and more. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [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. | | +| [Run an agile iteration](agile_sprint/index.md) | Use group, projects, and iterations to run an agile development iteration. | +| <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/scan_result_policy.md b/doc/tutorials/scan_result_policy.md new file mode 100644 index 00000000000..9aacd8eff7b --- /dev/null +++ b/doc/tutorials/scan_result_policy.md @@ -0,0 +1,11 @@ +--- +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 new file mode 100644 index 00000000000..6f4feb9ec4f --- /dev/null +++ b/doc/tutorials/scan_result_policy/index.md @@ -0,0 +1,125 @@ +--- +stage: Govern +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)** + +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. + +Prerequisites: + +The namespace used for this tutorial must: + +- Contain a minimum of three users, including your own. If you don't have two other users, you must first + create them. For details, see [Creating users](../../user/profile/account/create_accounts.md). + +To set up a scan result policy: + +1. [Create a test project](#create-a-test-project). +1. [Add a scan result policy](#add-a-scan-result-policy). +1. [Test the scan result policy](#test-the-scan-result-policy). + +## Create a test project + +1. On the top bar, select **Main menu > Projects**. +1. Select **New project**. +1. Select **Create blank project**. +1. Complete the fields. + - **Project name**: `sast-scan-result-policy`. + - Select the **Enable Static Application Security Testing (SAST)** checkbox. +1. Select **Create project**. + +## Add a scan result policy + +Next, you'll add a scan result policy to your test project: + +1. On the top bar, select **Main menu > Projects** and find the `sast-scan-result-policy` project. +1. On the left sidebar, go to **Security and Compliance > Policies**. +1. Select **New policy**. +1. In **Scan result policy**, select **Select policy**. +1. Complete the fields. + - **Name**: `sast-scan-result-policy` + - **Policy status**: **Enabled** +1. Add the following rule: + + ```plaintext + IF |Security Scan| from |SAST| find(s) more than |0| |All severity levels| |All vulnerability states| vulnerabilities in an open merge request targeting |All protected branches| + ``` + +1. Set **Actions** to the following: + + ```plaintext + THEN Require approval from | 2 | of the following approvers: + ``` + +1. Select two users. +1. Select **Configure with a merge request**. + + The application creates a new project to store the policies linked to it, and creates a merge request to define the policy. + +1. Select **Merge**. +1. On the top bar, select **Main menu > Projects** and select the `sast-scan-result-policy` project. +1. On the left sidebar, select **Security and Compliance > Policies**. + + You can see the list of policies added in the previous steps. + +## Test the scan result policy + +Nice work, you've created a scan result policy. To test it, create some vulnerabilities and check the result: + +1. On the top bar, select **Main menu > Projects** and select the `sast-scan-result-policy` project. +1. On the left sidebar, select **Repository > Files**. +1. From the **Add** (**{plus}**) dropdown list, select **New file**. +1. In the **Filename** field enter `main.ts`. +1. In the file's content, copy the following: + + ```typescript + // Non-literal require - tsr-detect-non-literal-require + var lib: String = 'fs' + require(lib) + + // Eval with variable - tsr-detect-eval-with-expression + var myeval: String = 'console.log("Hello.");'; + eval(myeval); + + // Unsafe Regexp - tsr-detect-unsafe-regexp + const regex: RegExp = /(x+x+)+y/; + + // Non-literal Regexp - tsr-detect-non-literal-regexp + var myregexpText: String = "/(x+x+)+y/"; + var myregexp: RegExp = new RegExp(myregexpText); + myregexp.test("(x+x+)+y"); + + // Markup escaping disabled - tsr-detect-disable-mustache-escape + var template: Object = new Object; + template.escapeMarkup = false; + + // Detects HTML injections - tsr-detect-html-injection + var element: Element = document.getElementById("mydiv"); + var content: String = "mycontent" + Element.innerHTML = content; + + // Timing attack - tsr-detect-possible-timing-attacks + var userInput: String = "Jane"; + var auth: String = "Jane"; + if (userInput == auth) { + console.log(userInput); + } + ``` + +1. In the **Commit message** field, enter `Add vulnerable file`. +1. In the **Target Branch** field, enter `test-branch`. +1. Select **Commit changes**. The **New merge request** form opens. +1. Select **Create merge request**. +1. In the new merge request, select `Create merge request`. + + Wait for the pipeline to complete. This could be a few minutes. + +The merge request security widget confirms that security scanning detected one potential +vulnerability. As defined in the scan result policy, the merge request is blocked and waiting for +approval. + +You now know how to set up and use scan result policies to catch vulnerabilities! diff --git a/doc/tutorials/secure_application.md b/doc/tutorials/secure_application.md new file mode 100644 index 00000000000..5b7d8733d63 --- /dev/null +++ b/doc/tutorials/secure_application.md @@ -0,0 +1,17 @@ +--- +stage: none +group: Tutorials +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Secure your application and check compliance + +GitLab can check your application for security vulnerabilities and that it meets compliance requirements. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Set up dependency scanning](https://about.gitlab.com/blog/2021/01/14/try-dependency-scanning/) | Try out dependency scanning, which checks for known vulnerabilities in dependencies. | **{star}** | +| [Create a compliance pipeline](compliance_pipeline/index.md) | Learn how to create compliance pipelines for your groups. | **{star}** | +| [Set up a scan result policy](scan_result_policy/index.md) | Learn how to configure a scan result policy that takes action based on scan results. | **{star}** | +| [Get started with GitLab application security](../user/application_security/get-started-security.md) | Follow recommended steps to set up security tools. | | +| [GitLab Security Essentials](https://levelup.gitlab.com/courses/security-essentials) | Learn about the essential security capabilities of GitLab in this self-paced course. | | |
