diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-10-12 12:09:42 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-10-12 12:09:42 +0300 |
commit | 7b3a8386ceeeb87b6e7e2e5ac00365f0d063cbb8 (patch) | |
tree | ae4cab5d1cffaaa70cf55bb52b7ae181847510ae /doc | |
parent | acc3d48da4fa0dcd2f2c8500c7cb7cc5c957300f (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/administration/settings/jira_cloud_app.md | 3 | ||||
-rw-r--r-- | doc/architecture/blueprints/cells/impacted_features/contributions-forks.md | 55 | ||||
-rw-r--r-- | doc/ci/migration/github_actions.md | 701 | ||||
-rw-r--r-- | doc/user/product_analytics/index.md | 6 | ||||
-rw-r--r-- | doc/user/usage_quotas.md | 32 |
5 files changed, 763 insertions, 34 deletions
diff --git a/doc/administration/settings/jira_cloud_app.md b/doc/administration/settings/jira_cloud_app.md index 1b92e20d705..f4f1db3617e 100644 --- a/doc/administration/settings/jira_cloud_app.md +++ b/doc/administration/settings/jira_cloud_app.md @@ -100,8 +100,9 @@ To link your self-managed instance to the GitLab for Jira Cloud app: 1. Select **GitLab (self-managed)**. 1. Enter your GitLab instance URL. 1. Select **Save**. +1. Optional. [Check if Jira Cloud is now linked](#check-if-jira-cloud-is-linked). -### Check if Jira Cloud is linked +#### Check if Jira Cloud is linked You can use the [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session) to check if Jira Cloud is linked to: diff --git a/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md b/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md index 2053b87b125..ccac5a24718 100644 --- a/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md +++ b/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md @@ -53,7 +53,9 @@ From a [data exploration](https://gitlab.com/gitlab-data/product-analytics/-/iss - The remaining 14% are forked from a source Project within a different company. - 9% of top-level Groups (95k) with activity in the last 12 months have a project with a fork relationship, compared to 5% of top-level Groups (91k) with no activity in the last 12 months. We expect these top-level Groups to be impacted by Cells. -## 3. Proposal - Forks are created in a dedicated contribution space of the current Organization +## 3. Proposals + +### 3.1. Forks are created in a dedicated contribution space of the current Organization Instead of creating Projects across Organizations, forks are created in a contribution space tied to the Organization. A contribution space is similar to a personal namespace but rather than existing in the default Organization, it exists within the Organization someone is trying to contribute to. @@ -74,11 +76,9 @@ Example: - Data in contribution spaces do not contribute to customer usage from a billing perspective. - Today we do not have organization-scoped runners but if we do implement that they will likely need special settings for how or if they can be used by contribution space projects. -## 4. Alternative proposals considered - -### 4.1. Intra-cluster forks +### 3.2. Intra-cluster forks -This proposal implements forks as intra-Cluster forks where communication is done via API between all trusted Cells of a cluster: +This proposal implements forks as intra-cluster forks where communication is done via API between all trusted Cells of a cluster: - Forks are created always in the context of a user's choice of Group. - Forks are isolated from the Organization. @@ -98,7 +98,7 @@ Cons: - However, this is no different to the ability of users today to clone a repository to a local computer and push it to any repository of choice. - Access control of the source Project can be lower than that of the target Project. Today, the system requires that in order to contribute back, the access level needs to be the same for fork and upstream Project. -### 4.2. Forks are created as internal Projects under current Projects +### 3.3. Forks are created as internal Projects under current Projects Instead of creating Projects across Organizations, forks are attachments to existing Projects. Each user forking a Project receives their unique Project. @@ -114,13 +114,37 @@ Cons: - Does not answer how to handle and migrate all existing forks. - Might share current Group/Project settings, which could be breaking some security boundaries. -## 5. Evaluation +### 3.4. Forks are created in personal namespaces of the current Organization + +Every User can potentially have a personal namespace in each public Organization. +On the first visit to an Organization the User will receive a personal namespace scoped to that Organization. +A User can fork into a personal namespace provided the upstream repository is in the same Organization as the personal namespace. +Removal of an Organization will remove any personal namespaces in the Organization. + +Pros: + +- We re-use most existing code paths. +- We re-use most existing product design rules. +- Organization boundaries are naturally isolated. +- Multiple personal namespaces will mean Users can divide personal Projects across Organizations instead of having them mixed together. +- We expect most Users to work in one Organization, which means that the majority of them would not need to remember in which Organization they stored each of their personal Projects. + +Cons: + +- Redundant personal namespaces will be created. We expect to improve this in future iterations. +- Multiple personal namespaces could be difficult to navigate, especially when working across a large number of Organizations. We expect this to be an edge case. +- The life cycle of personal namespaces will be dependent on the Organization as is already the case for user accounts privately owned (such as Enterprise Users), and self-managed installations that are not public. +- Organization personal namespaces will need new URL paths. +- The legacy personal namespace path will need to be adapted. + +URL path changes are under [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/427367). -### 5.1. Pros +## 4. Evaluation -### 5.2. Cons +We will follow [3.4. Forks are created in personal namespaces of the current Organization](#34-forks-are-created-in-personal-namespaces-of-the-current-organization) because it has already solved a lot of the hard problems. +The short falls of this solution like reworking URL paths or handling multiple personal namespaces are manageable and less critical than problems created through other alternative proposals. -## 6. Example +## 5. Example As an example, we will demonstrate the impact of this proposal for the case that we move `gitlab-org/gitlab` to a different Organization. `gitlab-org/gitlab` has [over 8K forks](https://gitlab.com/gitlab-org/gitlab/-/forks). @@ -128,9 +152,9 @@ As an example, we will demonstrate the impact of this proposal for the case that ### Does this direction impact the canonical URLs of those forks? Yes canonical URLs will change for forks. -Existing users that have forks in personal namespaces and want to continue contributing merge requests, will be required to migrate their fork to a new fork in a contribution space. -For example, a personal namespace fork at `https://gitlab.com/DylanGriffith/gitlab` will -need to be migrated to `https://gitlab.com/-/contributions/gitlab-inc/@DylanGriffith/gitlab`. +Specific path changes are under [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/427367). +Existing Users that have forks in legacy personal namespaces and want to continue contributing merge requests, will be required to migrate their fork to their personal namespace in the source project Organization. +For example, a personal namespace fork at `https://gitlab.com/DylanGriffith/gitlab` will need to be migrated to `https://gitlab.com/-/organizations/gitlab-inc/@DylanGriffith/gitlab`. We may offer automated ways to move this, but manually the process would involve: 1. Create the contribution space fork @@ -140,12 +164,11 @@ We may offer automated ways to move this, but manually the process would involve ### Does it impact the Git URL of the repositories themselves? Yes. -In the above the example the Git URL would change from -`gitlab.com:DylanGriffith/gitlab.git` to `gitlab.com:/-/contributions/gitlab-inc/@DylanGriffith/gitlab.git`. +Specific path changes are under [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/427367). ### Would there be any user action required to accept their fork being moved within an Organization or towards a contribution space? -If we offer an automated process we'd present this as an option for the user as they will become the new owner of the contribution space. +No. If the Organization is public, then a user will have a personal namespace. ### Can we make promises that we will not break the existing forks of public Projects hosted on GitLab.com? diff --git a/doc/ci/migration/github_actions.md b/doc/ci/migration/github_actions.md new file mode 100644 index 00000000000..86ce6c4846a --- /dev/null +++ b/doc/ci/migration/github_actions.md @@ -0,0 +1,701 @@ +--- +stage: Verify +group: Pipeline Authoring +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 +type: index, howto +--- + +# Migrating from GitHub Actions **(FREE ALL)** + +If you're migrating from GitHub Actions to GitLab CI/CD, you are able to create CI/CD +pipelines that replicate and enhance your GitHub Action workflows. + +## Key Similarities and Differences + +GitHub Actions and GitLab CI/CD are both used to generate pipelines to automate building, testing, +and deploying your code. Both share similarities including: + +- CI/CD functionality has direct access to the code stored in the project repository. +- Pipeline configurations written in YAML and stored in the project repository. +- Pipelines are configurable and can run in different stages. +- Jobs can each use a different container image. + +Additionally, there are some important differences between the two: + +- GitHub has a marketplace for downloading 3rd-party actions, which might require additional support or licenses. +- Self-managed GitLab instances support both horizontal and vertical scaling, while + GitHub Enterprise Server only supports vertical scaling. +- GitLab maintains and supports all features in house, and some 3rd-party integrations + are accessible through templates. +- GitLab provides a built-in container registry. +- GitLab has native Kubernetes deployment support. +- GitLab provides granular security policies. + +## Comparison of features and concepts + +Many GitHub features and concepts have equivalents in GitLab that offer the same +functionality. + +### Configuration file + +GitHub Actions can be configured with a [workflow YAML file](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#understanding-the-workflow-file). +GitLab CI/CD uses a [`.gitlab-ci.yml` YAML file](../../ci/yaml/gitlab_ci_yaml.md) by default. + +For example, in a GitHub Actions `workflow` file: + +```yaml +on: [push] +jobs: + hello: + runs-on: ubuntu-latest + steps: + - run: echo "Hello World" +``` + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +stages: + - hello + +hello: + stage: hello + script: + - echo "Hello World" +``` + +### GitHub Actions workflow syntax + +A GitHub Actions configuration is defined in a `workflow` YAML file using specific keywords. +GitLab CI/CD has similar functionality, also usually configured with YAML keywords. + +| GitHub | GitLab | Explanation | +|-----------|----------------|-------------| +| `env` | `variables` | `env` defines the variables set in a workflow, job, or step. GitLab uses `variables` to define [CI/CD variables](../variables/index.md) at the global or job level. Variables can also be added in the UI. | +| `jobs` | `stages` | `jobs` groups together all the jobs that run in the workflow. GitLab uses `stages` to group jobs together. | +| `on` | Not applicable | `on` defines when a workflow is triggered. GitLab is integrated tightly with Git, so SCM polling options for triggers are not needed, but can be configured per job if required. | +| `run` | Not applicable | The command to execute in the job. GitLab uses a YAML array under the `script` keyword, one entry for each command to execute. | +| `runs-on` | `tags` | `runs-on` defines the GitHub runner that a job must run on. GitLab uses `tags` to select a runner. | +| `steps` | `script` | `steps` groups together all the steps that run in a job. GitLab uses `script` to group together all the commands run in a job. | +| `uses` | `include` | `uses` defines what GitHub Action to be added to a `step`. GitLab uses `include` to add configuration from other files to a job. | + +### Common configurations + +This section goes over commonly used CI/CD configurations, showing how they can be converted +from GitHub Actions to GitLab CI/CD. + +[GitHub Action workflows](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#workflows) +generate automated CI/CD jobs that are triggered when certain event take place, for example +pushing a new commit. A GitHub Action workflow is a YAML file defined in the `.github/workflows` +directory located in the root of the repository. The GitLab equivalent is the +[`.gitlab-ci.yml` configuration file](../../ci/yaml/gitlab_ci_yaml.md) which also resides +in the repository's root directory. + +#### Jobs + +Jobs are a set of commands that run in a set sequence to achieve a particular result, +for example building a container or deploying to production. + +For example, this GitHub Actions `workflow` builds a container then deploys it to production. +The jobs runs sequentially, because the `deploy` job depends on the `build` job: + +```yaml +on: [push] +jobs: + build: + runs-on: ubuntu-latest + container: golang:alpine + steps: + - run: apk update + - run: go build -o bin/hello + - uses: actions/upload-artifact@v3 + with: + name: hello + path: bin/hello + retention-days: 7 + deploy: + if: contains( github.ref, 'staging') + runs-on: ubuntu-latest + container: golang:alpine + steps: + - uses: actions/download-artifact@v3 + with: + name: hello + - run: echo "Deploying to Staging" + - run: scp bin/hello remoteuser@remotehost:/remote/directory +``` + +This example: + +- Uses the `golang:alpine` container image. +- Runs a job for building code. + - Stores build executable as artifact. +- Runs a second job to deploy to `staging`, which also: + - Requires the build job to succeed before running. + - Requires the commit target branch `staging`. + - Uses the build executable artifact. + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +default: + image: golang:alpine + +stages: + - build + - deploy + +build-job: + stage: build + script: + - apk update + - go build -o bin/hello + artifacts: + paths: + - bin/hello + expire_in: 1 week + +deploy-job: + stage: deploy + script: + - echo "Deploying to Staging" + - scp bin/hello remoteuser@remotehost:/remote/directory + rules: + - if: $CI_COMMIT_BRANCH == 'staging' +``` + +##### Parallel + +In both GitHub and GitLab, Jobs run in parallel by default. + +For example, in a GitHub Actions `workflow` file: + +```yaml +on: [push] +jobs: + python-version: + runs-on: ubuntu-latest + container: python:latest + steps: + - run: python --version + java-version: + if: contains( github.ref, 'staging') + runs-on: ubuntu-latest + container: openjdk:latest + steps: + - run: java -version +``` + +This example runs a Python job and a Java job in parallel, using different container images. +The Java job only runs when the `staging` branch is changed. + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +python-version: + image: python:latest + script: + - python --version + +java-version: + image: openjdk:latest + rules: + - if: $CI_COMMIT_BRANCH == 'staging' + script: + - java -version +``` + +In this case, no extra configuration is needed to make the jobs run in parallel. +Jobs run in parallel by default, each on a different runner assuming there are enough runners +for all the jobs. The Java job is set to only run when the `staging` branch is changed. + +##### Matrix + +In both GitLab and GitHub you can use a matrix to run a job multiple times in parallel in a single pipeline, +but with different variable values for each instance of the job. + +For example, in a GitHub Actions `workflow` file: + +```yaml +on: [push] +jobs: + build: + runs-on: ubuntu-latest + steps: + - run: echo "Building $PLATFORM for $ARCH" + strategy: + matrix: + platform: [linux, mac, windows] + arch: [x64, x86] + test: + runs-on: ubuntu-latest + steps: + - run: echo "Testing $PLATFORM for $ARCH" + strategy: + matrix: + platform: [linux, mac, windows] + arch: [x64, x86] + deploy: + runs-on: ubuntu-latest + steps: + - run: echo "Deploying $PLATFORM for $ARCH" + strategy: + matrix: + platform: [linux, mac, windows] + arch: [x64, x86] +``` + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +stages: + - build + - test + - deploy + +.parallel-hidden-job: + parallel: + matrix: + - PLATFORM: [linux, mac, windows] + ARCH: [x64, x86] + +build-job: + extends: .parallel-hidden-job + stage: build + script: + - echo "Building $PLATFORM for $ARCH" + +test-job: + extends: .parallel-hidden-job + stage: test + script: + - echo "Testing $PLATFORM for $ARCH" + +deploy-job: + extends: .parallel-hidden-job + stage: deploy + script: + - echo "Deploying $PLATFORM for $ARCH" +``` + +#### Trigger + +GitHub Actions requires you to add a trigger for your workflow. GitLab is integrated tightly with Git, +so SCM polling options for triggers are not needed, but can be configured per job if required. + +Sample GitHub Actions configuration: + +```yaml +on: + push: + branches: + - main +``` + +The equivalent GitLab CI/CD configuration would be: + +```yaml +rules: + - if: '$CI_COMMIT_BRANCH == main' +``` + +Pipelines can also be [scheduled by using Cron syntax](../pipelines/schedules.md). + +#### Container Images + +With GitLab you can [run your CI/CD jobs in separate, isolated Docker containers](../../ci/docker/using_docker_images.md) +by using the [`image`](../../ci/yaml/index.md#image) keyword. + +For example, in a GitHub Actions `workflow` file: + +```yaml +jobs: + update: + runs-on: ubuntu-latest + container: alpine:latest + steps: + - run: apk update +``` + +In this example the `apk update` command runs in an `alpine:latest` container. + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +update-job: + image: alpine:latest + script: + - apk update +``` + +GitLab provides every project a [container registry](../../user/packages/container_registry/index.md) +for hosting container images. Container images can be built and stored directly from +GitLab CI/CD pipelines. + +For example: + +```yaml +stages: + - build + +build-image: + stage: build + variables: + IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA + before_script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + script: + - docker build -t $IMAGE . + - docker push $IMAGE +``` + +#### Variables + +In GitLab, we use the `variables` keyword to define different [CI/CD variables](../variables/index.md) at runtime. +Use variables when you need to reuse configuration data in a pipeline. You can define +variables globally or per job. + +For example, in a GitHub Actions `workflow` file: + +```yaml +env: + NAME: "fern" + +jobs: + english: + runs-on: ubuntu-latest + env: + Greeting: "hello" + steps: + - run: echo "$GREETING $NAME" + spanish: + runs-on: ubuntu-latest + env: + Greeting: "hola" + steps: + - run: echo "$GREETING $NAME" +``` + +In this example, variables provide different outputs for the jobs. + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +default: + image: ubuntu-latest + +variables: + NAME: "fern" + +english: + variables: + GREETING: "hello" + script: + - echo "$GREETING $NAME" + +spanish: + variables: + GREETING: "hola" + script: + - echo "$GREETING $NAME" +``` + +Variables can also be set up through the GitLab UI, under CI/CD settings, where you can +[protect](../variables/index.md#protect-a-cicd-variable) or [mask](../variables/index.md#mask-a-cicd-variable) +the variables. Masked variables are hidden in job logs, while protected variables +can only be accessed in pipelines for protected branches or tags. + +For example, in a GitHub Actions `workflow` file: + +```yaml +jobs: + login: + runs-on: ubuntu-latest + env: + AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }} + steps: + - run: my-login-script.sh "$AWS_ACCESS_KEY" +``` + +If the `AWS_ACCESS_KEY` variable is defined in the GitLab project settings, the equivalent +GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +login: + script: + - my-login-script.sh $AWS_ACCESS_KEY +``` + +Additionally, [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/contexts) +and [GitLab CI/CD](../../ci/variables/predefined_variables.md) provide built-in variables +which contain data relevant to the pipeline and repository. + +#### Conditionals + +When a new pipeline starts, GitLab checks the pipeline configuration to determine +which jobs should run in that pipeline. You can use the [`rules` keyword](../yaml/index.md#rules) +to configure jobs to run depending on conditions like the status of variables, or the pipeline type. + +For example, in a GitHub Actions `workflow` file: + +```yaml +jobs: + deploy_staging: + if: contains( github.ref, 'staging') + runs-on: ubuntu-latest + steps: + - run: echo "Deploy to staging server" +``` + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +deploy_staging: + stage: deploy + script: + - echo "Deploy to staging server" + rules: + - if: '$CI_COMMIT_BRANCH == staging' +``` + +#### Runners + +Runners are the services that execute jobs. If you are using GitLab.com, you can use the +[shared runner fleet](../runners/index.md) to run jobs without provisioning your own self-managed runners. + +Some key details about runners: + +- Runners can be [configured](../runners/runners_scope.md) to be shared across an instance, + a group, or dedicated to a single project. +- You can use the [`tags` keyword](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) + for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that + require dedicated, more powerful, or specific hardware. +- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). + Use autoscaling to provision runners only when needed and scale down when not needed. + +For example, in a GitHub Actions `workflow` file: + +```yaml +linux_job: + runs-on: ubuntu-latest + steps: + - run: echo "Hello, $USER" + +windows_job: + runs-on: windows-latest + steps: + - run: echo "Hello, %USERNAME%" +``` + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +linux_job: + stage: build + tags: + - linux-runners + script: + - echo "Hello, $USER" + +windows_job: + stage: build + tags: + - windows-runners + script: + - echo "Hello, %USERNAME%" +``` + +#### Artifacts + +In GitLab, any job can use the [artifacts](../../ci/yaml/index.md#artifacts) keyword to define a set +of artifacts to be stored when a job completes. [Artifacts](../../ci/jobs/job_artifacts.md) are files +that can be used in later jobs. + +For example, in a GitHub Actions `workflow` file: + +```yaml +on: [push] +jobs: + generate_cat: + steps: + - run: touch cat.txt + - run: echo "meow" > cat.txt + - uses: actions/upload-artifact@v3 + with: + name: cat + path: cat.txt + retention-days: 7 + use_cat: + needs: [generate_cat] + steps: + - uses: actions/download-artifact@v3 + with: + name: cat + - run: cat cat.txt +``` + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +stage: + - generate + - use + +generate_cat: + stage: generate + script: + - touch cat.txt + - echo "meow" > cat.txt + artifacts: + paths: + - cat.txt + expire_in: 1 week + +use_cat: + stage: use + script: + - cat cat.txt +``` + +#### Caching + +A [cache](../../ci/caching/index.md) is created when a job downloads one or more files and +saves them for faster access in the future. Subsequent jobs that use the same cache don't have to download the files again, +so they execute more quickly. The cache is stored on the runner and uploaded to S3 if +[distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). + +For example, in a GitHub Actions `workflow` file: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + - run: echo "This job uses a cache." + - uses: actions/cache@v3 + with: + path: binaries/ + key: binaries-cache-$CI_COMMIT_REF_SLUG +``` + +The equivalent GitLab CI/CD `.gitlab-ci.yml` file would be: + +```yaml +cache-job: + script: + - echo "This job uses a cache." + cache: + key: binaries-cache-$CI_COMMIT_REF_SLUG + paths: + - binaries/ +``` + +#### Templates + +In GitHub an Action is a set of complex tasks that need to be frequently repeated and is saved +to enable reuse without redefining a CI/CD pipeline. In GitLab the equivalent to an action would +be a the [`include` keyword](../yaml/includes.md), which allows you to [add CI/CD pipelines from other files](../../ci/yaml/includes.md), +including template files built into GitLab. + +Sample GitHub Actions configuration: + +```yaml +- uses: hashicorp/setup-terraform@v2.0.3 +``` + +The equivalent GitLab CI/CD configuration would be: + +```yaml +include: + - template: Terraform.gitlab-ci.yml +``` + +In these examples, the `setup-terraform` GitHub action and the `Terraform.gitlab-ci.yml` GitLab template +are not exact matches. These two examples are just to show how complex configuration can be reused. + +### Security Scanning features + +GitLab provides a variety of [security scanners](../../user/application_security/index.md) +out-of-the-box to detect vulnerabilities in all parts of the SLDC. You can add these features +to your GitLab CI/CD pipeline by using templates. + +for example to add SAST scanning to your pipeline, add the following to your `.gitlab-ci.yml`: + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml +``` + +You can customize the behavior of security scanners by using CI/CD variables, for example +with the [SAST scanners](../../user/application_security/sast/index.md#available-cicd-variables). + +### Secrets Management + +Privileged information, often referred to as "secrets", is sensitive information +or credentials you need in your CI/CD workflow. You might use secrets to unlock protected resources +or sensitive information in tools, applications, containers, and cloud-native environments. + +For secrets management in GitLab, you can use one of the supported integrations +for an external service. These services securely store secrets outside of your GitLab project, +though you must have a subscription for the service: + +- [HashiCorp Vault](../secrets/id_token_authentication.md#automatic-id-token-authentication-with-hashicorp-vault). +- [Azure Key Vault](../secrets/azure_key_vault.md). + +GitLab also supports [OIDC authentication](../secrets/id_token_authentication.md) +for other third party services that support OIDC. + +Additionally, you can make credentials available to jobs by storing them in CI/CD variables, though secrets +stored in plain text are susceptible to accidental exposure. You should always store sensitive information +in [masked](../variables/index.md#mask-a-cicd-variable) and [protected](../variables/index.md#protect-a-cicd-variable) +variables, which mitigates some of the risk. + +Also, never store secrets as variables in your `.gitlab-ci.yml` file, which is public to all +users with access to the project. Storing sensitive information in variables should +only be done in [the project, group, or instance settings](../variables/index.md#define-a-cicd-variable-in-the-ui). + +Review the [security guidelines](../variables/index.md#cicd-variable-security) to improve +the safety of your CI/CD variables. + +## Planning and Performing a Migration + +The following list of recommended steps was created after observing organizations +that were able to quickly complete this migration. + +### Create a Migration Plan + +Before starting a migration you should create a [migration plan](plan_a_migration.md) to make preparations for the migration. + +### Prerequisites + +Before doing any migration work, you should first: + +1. Get familiar with GitLab. + - Read about the [key GitLab CI/CD features](../../ci/index.md). + - Follow tutorials to create [your first GitLab pipeline](../quick_start/index.md) and [more complex pipelines](../quick_start/tutorial.md) that build, test, and deploys a static site. + - Review the [`.gitlab-ci.yml` keyword reference](../yaml/index.md). +1. Set up and configure GitLab. +1. Test your GitLab instance. + - Ensure [runners](../runners/index.md) are available, either by using shared GitLab.com runners or installing new runners. + +### Migration Steps + +1. Migrate Projects from GitHub to GitLab: + - (Recommended) You can use the [GitHub Importer](../../user/project/import/github.md) + to automate mass imports from external SCM providers. + - You can [import repositories by URL](../../user/project/import/repo_by_url.md). +1. Create a `.gitlab-ci.yml` in each project. +1. Migrate GitHub Actions jobs to GitLab CI/CD jobs and configure them to show results directly in merge requests. +1. Migrate deployment jobs by using [cloud deployment templates](../cloud_deployment/index.md), + [environments](../environments/index.md), and the [GitLab agent for Kubernetes](../../user/clusters/agent/index.md). +1. Check if any CI/CD configuration can be reused across different projects, then create + and share [CI/CD templates](../../development/cicd/templates.md) +1. Check the [pipeline efficiency documentation](../pipelines/pipeline_efficiency.md) + to learn how to make your GitLab CI/CD pipelines faster and more efficient. + +### Additional Resources + +- [Video: How to migrate from GitHub to GitLab including Actions](https://youtu.be/0Id5oMl1Kqs?feature=shared) +- [Blog: GitHub to GitLab migration the easy way](https://about.gitlab.com/blog/2023/07/11/github-to-gitlab-migration-made-easy/) + +If you have questions that are not answered here, the [GitLab community forum](https://forum.gitlab.com/) can be a great resource. diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 82991ffb2b1..ca55ab758da 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -20,7 +20,11 @@ This feature is not ready for production use. This page is a work in progress, and we're updating the information as we add more features. For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). -To leave feedback about Product Analytics bugs or functionality, please comment in [issue 391970](https://gitlab.com/gitlab-org/gitlab/-/issues/391970) or open a new issue with the label `group::product analytics`. +To leave feedback about Product Analytics bugs or functionality: + +- Comment on [issue 391970](https://gitlab.com/gitlab-org/gitlab/-/issues/391970). +- Create an issue with the `group::product analytics` label. +- [Schedule a call](https://calendly.com/jheimbuck/30-minute-call) with the team. ## How product analytics works diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index d717984e6d5..305a46e1f15 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -132,7 +132,7 @@ Depending on your role, to manage your transfer usage you can [reduce Container ## Project storage limit -Projects on GitLab SaaS have a 10 GB storage limit on their Git repository and LFS storage. +Projects on GitLab SaaS have a 10 GiB storage limit on their Git repository and LFS storage. After namespace-level storage limits are applied, the project limit is removed. A namespace has either a namespace-level storage limit or a project-level storage limit, but not both. When a project's repository and LFS reaches the quota, the project is set to a read-only state. @@ -162,28 +162,28 @@ The following example describes an excess storage scenario for a namespace: | Repository | Storage used | Excess storage | Quota | Status | |------------|--------------|----------------|--------|----------------------| -| Red | 10 GB | 0 GB | 10 GB | Read-only **{lock}** | -| Blue | 8 GB | 0 GB | 10 GB | Not read-only | -| Green | 10 GB | 0 GB | 10 GB | Read-only **{lock}** | -| Yellow | 2 GB | 0 GB | 10 GB | Not read-only | -| **Totals** | **30 GB** | **0 GB** | - | - | +| Red | 10 GiB | 0 GiB | 10 GiB | Read-only **{lock}** | +| Blue | 8 GiB | 0 GiB | 10 GiB | Not read-only | +| Green | 10 GiB | 0 GiB | 10 GiB | Read-only **{lock}** | +| Yellow | 2 GiB | 0 GiB | 10 GiB | Not read-only | +| **Totals** | **30 GiB** | **0 GiB** | - | - | The Red and Green projects are read-only because their repositories and LFS have reached the quota. In this example, no additional storage has yet been purchased. -To remove the read-only state from the Red and Green projects, 50 GB additional storage is purchased. +To remove the read-only state from the Red and Green projects, 50 GiB additional storage is purchased. -Assuming the Green and Red projects' repositories and LFS grow past the 10 GB quota, the purchased storage -available decreases. All projects no longer have the read-only status because 40 GB purchased storage is available: -50 GB (purchased storage) - 10 GB (total excess storage used). +Assuming the Green and Red projects' repositories and LFS grow past the 10 GiB quota, the purchased storage +available decreases. All projects no longer have the read-only status because 40 GiB purchased storage is available: +50 GiB (purchased storage) - 10 GiB (total excess storage used). | Repository | Storage used | Excess storage | Quota | Status | |------------|--------------|----------------|---------|-------------------| -| Red | 15 GB | 5 GB | 10 GB | Not read-only | -| Blue | 14 GB | 4 GB | 10 GB | Not read-only | -| Green | 11 GB | 1 GB | 10 GB | Not read-only | -| Yellow | 5 GB | 0 GB | 10 GB | Not read-only | -| **Totals** | **45 GB** | **10 GB** | - | - | +| Red | 15 GiB | 5 GiB | 10 GiB | Not read-only | +| Blue | 14 GiB | 4 GiB | 10 GiB | Not read-only | +| Green | 11 GiB | 1 GiB | 10 GiB | Not read-only | +| Yellow | 5 GiB | 0 GiB | 10 GiB | Not read-only | +| **Totals** | **45 GiB** | **10 GiB** | - | - | ## Namespace storage limit @@ -221,7 +221,7 @@ To prevent exceeding the namespace storage limit, you can: - [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/) - [GitLab for Startups](https://about.gitlab.com/solutions/startups/) - Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab, which does not have these limits on the Free tier. -- [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10 GB of storage. +- [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60 per year for 10 GiB of storage. - [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), which include higher limits and features to enable growing teams to ship faster without sacrificing on quality. - [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. |