From 9a1066298169f8ebecacb9e55fe895f4f8962000 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Fri, 17 Jun 2022 18:09:49 +0000 Subject: Add latest changes from gitlab-org/gitlab@master --- doc/ci/runners/configure_runners.md | 85 +++++++++++++++++++++++++++++++++++ doc/development/pages/index.md | 20 +++++++++ doc/development/pipelines.md | 12 +++++ doc/development/work_items.md | 22 ++++++--- doc/security/ssh_keys_restrictions.md | 9 ++-- 5 files changed, 138 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 714c405ad20..efd78fac2c6 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -718,6 +718,91 @@ variables: | `CACHE_COMPRESSION_LEVEL` | To adjust compression ratio, set to `fastest`, `fast`, `default`, `slow`, or `slowest`. This setting works with the Fastzip archiver only, so the GitLab Runner feature flag [`FF_USE_FASTZIP`](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) must also be enabled. | | `CACHE_REQUEST_TIMEOUT` | Configure the maximum duration of cache upload and download operations for a single job in minutes. Default is `10` minutes. | +## Artifact attestation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28940) in GitLab Runner 15.1. + +GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The file name is as follows: `{JOB_ID}-artifacts-metadata.json`. + +### Attestation format + +The attestation metadata is generated in the [in-toto attestation format](https://github.com/in-toto/attestation) for spec version [v0.1](https://in-toto.io/Statement/v0.1). The following fields are populated by default: + +| Field | Value | +| ------ | ------ | +| `_type` | `https://in-toto.io/Statement/v0.1` | +| `subject.name` | The filename of the artifact. | +| `subject.digest.sha256` | The artifact's `sha256` checksum. | +| `predicateType` | `https://slsa.dev/provenance/v0.2` | +| `predicate.buildType` | `https://gitlab.com/gitlab-org/gitlab-runner/-/blob/{GITLAB_RUNNER_VERSION}/PROVENANCE.md`. For example v15.0.0 | +| `predicate.builder.id` | A URI pointing to the runner details page, for example `https://gitlab.com/gitlab-com/www-gitlab-com/-/runners/3785264`. | +| `predicate.invocation.configSource.uri` | ``https://gitlab.example.com/.../{PROJECT_NAME}`` | +| `predicate.invocation.configSource.digest.sha256` | The repository's `sha256` checksum. | +| `predicate.invocation.configSource.entryPoint` | The name of the CI job that triggered the build. | +| `predicate.invocation.environment.name` | The name of the runner. | +| `predicate.invocation.environment.executor` | The runner executor. | +| `predicate.invocation.environment.architecture` | The architecture on which the CI job is run. | +| `predicate.invocation.parameters` | The names of any CI/CD or environment variables that were present when the build command was run. The value is always represented as an empty string to avoid leaking any secrets. | +| `metadata.buildStartedOn` | The time when the build was started. `RFC3339` formatted. | +| `metadata.buildEndedOn` | The time when the build ended. Since metadata generation happens during the build this moment in time will be slightly earlier than the one reported in GitLab. `RFC3339` formatted. | +| `metadata.reproducible` | Whether the build is reproducible by gathering all the generated metadata. Always `false`. | +| `metadata.completeness.parameters` | Whether the parameters are supplied. Always `true`. | +| `metadata.completeness.environment` | Whether the builder's environment is reported. Always `true`. | +| `metadata.completeness.materials` | Whether the build materials are reported. Always `false`. | + +An example of an attestation that the GitLab Runner might generate is as follows: + +```yaml +{ + "_type": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/v15.1.0/PROVENANCE.md", + "subject": [ + { + "name": "script.sh", + "digest": { + "sha256": "f5ae5ced234922eebe6461d32228ba8ab9c3d0c0f3983a3bef707e6e1a1ab52a" + } + } + ], + "predicateType": "https://slsa.dev/provenance/v0.2", + "predicate": { + "buildType": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/v15.1.0/PROVENANCE.md", + "builder": { + "id": "https://gitlab.com/ggeorgiev_gitlab/playground/-/runners/14811533" + }, + "invocation": { + "configSource": { + "uri": "https://gitlab.com/ggeorgiev_gitlab/playground", + "digest": { + "sha256": "f0582e2c9a16b5cc2cde90e8be8f1b50fd67c631" + }, + "entryPoint": "whoami shell" + }, + "environment": { + "name": "local", + "executor": "shell", + "architecture": "amd64" + }, + "parameters": { + "CI_PIPELINE_ID": "", + "CI_PIPELINE_URL": "", + // All other CI variable names are listed here. Values are always represented as empty strings to avoid leaking secrets. + } + }, + "metadata": { + "buildStartedOn": "2022-06-17T00:47:27+03:00", + "buildFinishedOn": "2022-06-17T00:47:28+03:00", + "completeness": { + "parameters": true, + "environment": true, + "materials": false + }, + "reproducible": false + }, + "materials": [] + } +} +``` + ### Staging directory > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3403) in GitLab Runner 15.0. diff --git a/doc/development/pages/index.md b/doc/development/pages/index.md index 8049d8c0a48..02019db48ba 100644 --- a/doc/development/pages/index.md +++ b/doc/development/pages/index.md @@ -185,11 +185,31 @@ GitLab Pages access control is disabled by default. To enable it: - 'gitlab-pages/gitlab-pages.conf' ``` +### Enabling object storage + +GitLab Pages support using object storage for storing artifacts, but object storage +is disabled by default. You can enable it in the GDK: + +1. Edit `gdk.yml` to enable the object storage in GitLab itself: + + ```yaml + # $GDK_ROOT/gdk.yml + object_store: + enabled: true + ``` + +1. Reconfigure and restart GitLab by running the commands `gdk reconfigure` and `gdk restart`. + +For more information, refer to the [GDK documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/configuration.md#object-storage-configuration). + ## Linting ```shell # Run the linter locally make lint + +# Run linter and fix issues (if supported by the linter) +make format ``` ## Testing diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 71e3b056f6b..436977a7f38 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -289,6 +289,18 @@ In the event of an emergency, or false positive from this job, add the `pipeline:skip-undercoverage` label to the merge request to allow this job to fail. +### Troubleshooting `rspec:undercoverage` failures + +The `rspec:undercoverage` job has [known bugs](https://gitlab.com/groups/gitlab-org/-/epics/8254) +that can cause false positive failures. You can locally test coverage locally to determine if it's +safe to apply `~"pipeline:skip-undercoverage"`. For example, using `` as the name of the +test causing the failure: + +1. Run `SIMPLECOV=1 bundle exec rspec `. +1. Run `scripts/undercoverage`. + +If these commands return `undercover: ✅ No coverage is missing in latest changes` then you can apply `~"pipeline:skip-undercoverage"` to bypass pipeline failures. + ## Ruby versions testing Our test suite runs against Ruby 2 in merge requests and default branch pipelines. diff --git a/doc/development/work_items.md b/doc/development/work_items.md index d4a1073461a..9a17a152525 100644 --- a/doc/development/work_items.md +++ b/doc/development/work_items.md @@ -45,12 +45,24 @@ Here are some problems with current issues usage and why we are looking into wor - Codebase maintainability and feature development becomes a bigger challenges as we grow issues beyond its core role of issue tracking into supporting the different types and subtle differences between them. -## Work item and work item type terms +## Work item terminology -Using the terms "issue" or "issuable" to reference the types of collaboration objects -(for example, issue, bug, feature, or epic) often creates confusion. To avoid confusion, we will use the term -work item type (WIT) when referring to the type of a collaboration object. -An instance of a WIT is a work item (WI). For example, `issue#123`, `bug#456`, `requirement#789`. +To avoid confusion and ensure communication is efficient, we will use the following terms exclusively when discussing work items. + +| Term | Description | Example of misuse | Should be | +| --- | --- | --- | --- | +| work item type | Classes of work item; for example: issue, requirement, test case, incident, or task | _Epics will eventually become issues_ | _Epics will eventually become a **work item type**_ | +| work item | An instance of a work item type | | | +| work item view | The new frontend view that renders work items of any type | | | +| legacy issue view | The existing view used to render issues and incidents | | | +| issue | The existing issue model | | | +| issuable | Any model currently using the issueable module (issues, epics and MRs) | _Incidents are an **issuable**_ | _Incidents are a **work item type**_ | + +Some terms have been used in the past but have since become confusing and are now discouraged. + +| Term | Description | Example of misuse | Should be | +| --- | --- | --- | --- | +| issue type | A former way to refer to classes of work item | _Tasks are an **issue type**_ | _Tasks are a **work item type**_ | ### Migration strategy diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 953a5b30fce..eb92694d236 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -50,13 +50,12 @@ By default, the GitLab.com and self-managed settings for the ### Block banned or compromised keys **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24614) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `ssh_banned_key`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24614) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `ssh_banned_key`. Enabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `ssh_banned_key`. -On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. -The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature per user, +ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `ssh_banned_key`. +On GitLab.com, this feature is available. When users attempt to [add a new SSH key](../user/ssh.md#add-an-ssh-key-to-your-gitlab-account) to GitLab accounts, the key is checked against a list of SSH keys which are known -- cgit v1.2.1