diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.vale/gitlab/spelling-exceptions.txt | 1 | ||||
| -rw-r--r-- | doc/api/graphql/reference/index.md | 1 | ||||
| -rw-r--r-- | doc/architecture/blueprints/ci_pipeline_components/index.md | 26 | ||||
| -rw-r--r-- | doc/integration/diffblue-cover.md | 89 | ||||
| -rw-r--r-- | doc/integration/img/diffblue_cover_diff_v16_8.png | bin | 0 -> 95590 bytes | |||
| -rw-r--r-- | doc/integration/img/diffblue_cover_workflow_after_v16_8.png | bin | 0 -> 42684 bytes | |||
| -rw-r--r-- | doc/user/project/integrations/mattermost.md | 4 |
7 files changed, 118 insertions, 3 deletions
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index cc02821b6d6..b8cc7d4d890 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -284,6 +284,7 @@ devfiles DevOps Dhall dialogs +Diffblue disambiguates discoverability dismissable diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index a7e6409b8aa..f17d9794568 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -31552,6 +31552,7 @@ State of a Sentry error. | <a id="servicetypeconfluence_service"></a>`CONFLUENCE_SERVICE` | ConfluenceService type. | | <a id="servicetypecustom_issue_tracker_service"></a>`CUSTOM_ISSUE_TRACKER_SERVICE` | CustomIssueTrackerService type. | | <a id="servicetypedatadog_service"></a>`DATADOG_SERVICE` | DatadogService type. | +| <a id="servicetypediffblue_cover_service"></a>`DIFFBLUE_COVER_SERVICE` | DiffblueCoverService type. | | <a id="servicetypediscord_service"></a>`DISCORD_SERVICE` | DiscordService type. | | <a id="servicetypedrone_ci_service"></a>`DRONE_CI_SERVICE` | DroneCiService type. | | <a id="servicetypeemails_on_push_service"></a>`EMAILS_ON_PUSH_SERVICE` | EmailsOnPushService type. | diff --git a/doc/architecture/blueprints/ci_pipeline_components/index.md b/doc/architecture/blueprints/ci_pipeline_components/index.md index 9a225c9cd97..78d9401d5a5 100644 --- a/doc/architecture/blueprints/ci_pipeline_components/index.md +++ b/doc/architecture/blueprints/ci_pipeline_components/index.md @@ -232,7 +232,7 @@ The version of the component can be (in order of highest priority first): 1. A commit SHA - For example: `gitlab.com/gitlab-org/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8` 1. A tag - For example: `gitlab.com/gitlab-org/dast@1.0` -1. A special moving target version that points to the most recent released tag - For example: `gitlab.com/gitlab-org/dast@~latest` +1. A special moving target version that points to the most recent published release - For example: `gitlab.com/gitlab-org/dast@~latest` 1. A branch name - For example: `gitlab.com/gitlab-org/dast@master` If a tag and branch exist with the same name, the tag takes precedence over the branch. @@ -244,6 +244,30 @@ As we want to be able to reference any revisions (even those not released), a co When referencing a component by local path (for example `./path/to/component`), its version is implicit and matches the commit SHA of the current pipeline context. +#### The `~latest` version + +The use of `~latest` version qualifier is restricted to only those releases that are published in the Catalog. + +We debated whether `~latest` should be supported for projects that are not marked as catalog resources. + +There are various reasons for this decision: + +1. Versions could be unlisted from the Catalog and `~latest` need to reflect that. +1. The Catalog will support private resources. There are currently no valid requirements for component projects to + have releases but not being published in the Catalog. +1. In the future we will be separating the process of releasing and publishing a release, allowing users to choose + what release is published in the catalog. +1. We could enforce better the use of semantic versioning when publishing a release, rejecting it if not following + the standard. We won't be able to enforce semantic versioning on the release model because it won't be backwards + compatible. +1. Latest version will likely be denormalized for a catalog resource data structure for more performant queries both + when displaying the Catalog resources and when fetching a component version. + +In all the points above, if we were supporting `~latest` for both catalog resources and unpublished component projects we could +introduce discrepancies and surprising behaviors. Starting with a stricter approach, like supporting +only published versions, we have the freedom to expand this in the future to support unpublished component projects based on +user demand. + ### Note about future resource types In the future, to support multiple types of resources in the Catalog we could diff --git a/doc/integration/diffblue-cover.md b/doc/integration/diffblue-cover.md new file mode 100644 index 00000000000..bd1d026b5ef --- /dev/null +++ b/doc/integration/diffblue-cover.md @@ -0,0 +1,89 @@ +--- +stage: Verify +group: Pipeline Execution +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" +description: >- + How to configure the Diffblue Cover GitLab integration - Cover Pipeline for + GitLab +--- + +# Diffblue Cover **(FREE ALL)** + +You can integrate the [Diffblue Cover](https://www.diffblue.com/) reinforcement learning AI tool into your CI/CD pipelines, to automatically write and maintain Java unit tests for your GitLab projects. +The Diffblue Cover Pipeline for GitLab integration allows you to automatically: + +- Write a baseline unit test suite for your projects. +- Write new unit tests for new code. +- Update existing unit tests in your code. +- Remove existing unit tests in your code when they're no longer required. + + + +## Configure the integration + +To integrate Diffblue Cover into your pipeline: + +1. Find and configure the Diffblue Cover integration. +1. Configure a pipeline for a sample project using the GitLab pipeline editor and the Diffblue Cover pipeline template. +1. Create a full baseline unit test suite for the project. + +### Configure Diffblue Cover + +1. On the left sidebar, select **Search or go to** and find your project. + - If you want to test the integration with a sample project, you can [import](../user/project/import/repo_by_url.md) + the Diffblue [Spring PetClinic sample project](https://github.com/diffblue/demo-spring-petclinic). +1. Select **Settings > Integrations**. +1. Find **Diffblue Cover** and select **Configure**. +1. Complete the fields: + + - Select the **Active** checkbox. + - Enter your Diffblue Cover **License key** provided in your welcome email or by your organization. + If needed, select the [**Try Diffblue Cover**](https://www.diffblue.com/try-cover/gitlab) link to sign up for a free trial. + - Enter details of your GitLab access token (**Name** and **Secret**) to allow Diffblue Cover to access your project. + In general, use a GitLab [project access token](../user/project/settings/project_access_tokens.md) with the `Developer` role, plus `api` and `write_repository` scopes. + If necessary you can use a [group access token](../user/group/settings/group_access_tokens.md) or a [personal access token](../user/profile/personal_access_tokens.md), again with the `Developer` role, plus `api` and `write_repository` scopes. + + NOTE: + Using an access token with excessive permissions is a security risk. + If you use a Personal access token, consider creating a dedicated user with access limited to just the project, minimizing the impact of the token being leaked. + +1. Select **Save changes**. + Your Diffblue Cover integration is now <mark style="color:green;">**Active**</mark> and ready for use in your project. + +### Configure a pipeline + +Here we'll create a merge request pipeline for the project that will download the latest version of Diffblue Cover, build the project, write Java unit tests for the project, and commit the changes to the branch. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Build > Pipeline editor**. +1. Select **Configure pipeline** to create the `.gitlab-ci.yml` file. +1. Select **Browse templates** and find the `Diffblue-Cover.gitlab-ci.yml` template file. +1. Select the file and copy the contents to your project's `.gitlab-ci.yml` file. + + NOTE: + When using the Diffblue Cover pipeline template with your own project and existing pipeline file, add the Diffblue template content to your file and modify as needed. + For more information, see [Cover Pipeline for GitLab](https://docs.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab) in the Diffblue documentation. + +1. Enter a commit message. +1. Enter a new **Branch** name. For example, `add-diffblue-cover-pipeline`. +1. Select **Start a new merge request with these changes**. +1. Select **Commit changes**. + +### Create a baseline unit test suite + +1. In the **New merge request** form, enter a **Title** (for example, "Add Cover pipeline and create baseline unit test suite") and fill out the other fields. +1. Select **Create merge request**. The merge request pipeline runs Diffblue Cover to create the baseline unit test suite for the project. +1. Once the pipeline completes, the changes can be reviewed from the **Changes** tab. When you're happy, merge the updates to your repo. Go to the `src/test` folders in the project repository to see the unit tests created by Diffblue Cover (suffixed with `*DiffblueTest.java`). + +## Subsequent code changes + +When performing subsequent code changes to a project, the merge request pipeline will run Diffblue Cover but will only update the associated tests. +The resulting diff can then be analyzed to check the new behavior, catch regressions, and spot any unplanned behavioral changes to the code. + + + +## Next steps + +This topic demonstrates some of the key features of Cover Pipeline for GitLab and how to use the integration in a pipeline. +The wider and deeper functionality, provided through `dcover` commands in the pipeline template, can be implemented to expand your unit test capabilities even further. +For more information, see [Cover Pipeline for GitLab](https://docs.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab) in the Diffblue documentation. diff --git a/doc/integration/img/diffblue_cover_diff_v16_8.png b/doc/integration/img/diffblue_cover_diff_v16_8.png Binary files differnew file mode 100644 index 00000000000..1ee4dd954af --- /dev/null +++ b/doc/integration/img/diffblue_cover_diff_v16_8.png diff --git a/doc/integration/img/diffblue_cover_workflow_after_v16_8.png b/doc/integration/img/diffblue_cover_workflow_after_v16_8.png Binary files differnew file mode 100644 index 00000000000..21345600125 --- /dev/null +++ b/doc/integration/img/diffblue_cover_workflow_after_v16_8.png diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 0a82a94d998..91c8e9ce2f1 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -19,8 +19,8 @@ To use the Mattermost integration you must create an incoming webhook integratio in Mattermost: 1. Sign in to your Mattermost instance. -1. [Enable incoming webhooks](https://docs.mattermost.com/developer/webhooks-incoming.html#enabling-incoming-webhooks). -1. [Add an incoming webhook](https://docs.mattermost.com/developer/webhooks-incoming.html#creating-integrations-using-incoming-webhooks). +1. [Enable incoming webhooks](https://docs.mattermost.com/configure/integrations-configuration-settings.html#enable-incoming-webhooks). +1. [Add an incoming webhook](https://developers.mattermost.com/integrate/webhooks/incoming/#create-an-incoming-webhook). 1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it and copy the **Webhook URL** because we need this later for GitLab. |
