Add latest changes from gitlab-org/gitlab@master

5 files changed, 212 insertions, 1 deletions

diff --git a/doc/user/packages/container_registry/img/expiration-policy-app.png b/doc/user/packages/container_registry/img/expiration-policy-app.png
new file mode 100644
index 00000000000..38de4d85ae5
--- /dev/null
+++ b/doc/user/packages/container_registry/img/expiration-policy-app.png
diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md
index 877379705de..97831d65759 100644
--- a/doc/user/packages/container_registry/index.md
+++ b/doc/user/packages/container_registry/index.md
@@ -138,6 +138,47 @@ Example of using a token:
 docker login registry.example.com -u <username> -p <token>
 ```
 
+## Expiration policy
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/15398) in GitLab 12.8.
+
+It is possible to create a per-project expiration policy, so that you can make sure that
+older tags and images are regularly removed from the Container Registry.
+
+### Managing project expiration policy through the API
+
+You can set, update, and disable the expiration policies using the GitLab API.
+
+Examples:
+
+- Select all tags, keep at least 1 tag per image, expire any tag older than 14 days, run once a month, and the policy is enabled:
+
+  ```bash
+  curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":".*"}' 'https://gitlab.example.com/api/v4/projects/2'
+  ```
+
+- Select only tags with a name that contains `stable`, keep at least 50 tag per image, expire any tag older than 7 days, run every day, and the policy is enabled:
+
+  ```bash
+  curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1day","enabled":true,"keep_n":50"older_than":"7d","name_regex":"*stable"}' 'https://gitlab.example.com/api/v4/projects/2'
+  ```
+
+See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project).
+
+### Managing project expiration policy through the UI
+
+To manage project expiration policy, navigate to **Settings > CI/CD > Container Registry tag expiration policy**.
+
+![Expiration Policy App](img/expiration-policy-app.png)
+
+The UI allows you to configure the following:
+
+- **Expiration policy:** enable or disable the expiration policy.
+- **Expiration interval:** how long tags are exempt from being deleted.
+- **Expiration schedule:** how often the cron job checking the tags should run.
+- **Expiration latest:** how many tags to _always_ keep for each image.
+- **Expire Docker tags with regex matching:** the regex used to determine what tags should be expired. To qualify all tags for expiration, use the default value of `.*`.
+
 ## Troubleshooting the GitLab Container Registry
 
 ### Docker connection error
diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md
index c58effac59d..80a3b1e1392 100644
--- a/doc/user/packages/index.md
+++ b/doc/user/packages/index.md
@@ -27,4 +27,5 @@ NOTE: **Note** We are especially interested in adding support for [PyPi](https:/
 
 Learning how to use the GitLab Package Registry will help you build your own custom package workflow.
 
-[Use a project as a package registry](./workflows/project_registry.md) to publish all of your packages to one project.
+- [Use a project as a package registry](./workflows/project_registry.md) to publish all of your packages to one project.
+- [Working with a monorepo](./workflows/monorepo.md): Learn how to publish multiple different packages from one monorepo project.
diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md
index da5139fcaf9..ea052703416 100644
--- a/doc/user/packages/maven_repository/index.md
+++ b/doc/user/packages/maven_repository/index.md
@@ -338,3 +338,53 @@ The next time the `deploy` job runs, it will copy `ci_settings.xml` to the
 user's home location (in this case the user is `root` since it runs in a
 Docker container), and Maven will utilize the configured CI
 [environment variables](../../../ci/variables/README.md#predefined-environment-variables).
+
+## Troubleshooting
+
+### Useful Maven command line options
+
+There's some [maven command line options](https://maven.apache.org/ref/current/maven-embedder/cli.html)
+which maybe useful when doing tasks with GitLab CI.
+
+- File transfer progress can make the CI logs hard to read.
+  Option `-ntp,--no-transfer-progress` was added in
+  [3.6.1](https://maven.apache.org/docs/3.6.1/release-notes.html#User_visible_Changes).
+  Alternatively, look at `-B,--batch-mode`
+  [or lower level logging changes.](https://stackoverflow.com/questions/21638697/disable-maven-download-progress-indication)
+
+- Specify where to find the POM file (`-f,--file`):
+
+   ```yaml
+   package:
+     script:
+       - 'mvn --no-transfer-progress -f helloworld/pom.xml package'
+   ```
+
+- Specify where to find the user settings (`-s,--settings`) instead of
+  [the default location](https://maven.apache.org/settings.html). There's also a `-gs,--global-settings` option:
+
+   ```yaml
+   package:
+     script:
+       - 'mvn -s settings/ci.xml package'
+   ```
+
+### Verifying your Maven settings
+
+If you encounter issues within CI that relate to the `settings.xml` file, it might be useful
+to add an additional script task or job to
+[verify the effective settings](https://maven.apache.org/plugins/maven-help-plugin/effective-settings-mojo.html).
+
+The help plugin can also provide
+[system properties](https://maven.apache.org/plugins/maven-help-plugin/system-mojo.html), including environment variables:
+
+```yaml
+mvn-settings:
+  script:
+    - 'mvn help:effective-settings'
+
+package:
+  script:
+    - 'mvn help:system'
+    - 'mvn package'
+```
diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md
new file mode 100644
index 00000000000..9f281d2b31c
--- /dev/null
+++ b/doc/user/packages/workflows/monorepo.md
@@ -0,0 +1,119 @@
+# Monorepo package management workflows
+
+Oftentimes, one project or Git repository may contain multiple different
+subprojects or submodules that all get packaged and published individually.
+
+## Publishing different packages to the parent project
+
+The number and name of packages you can publish to one project is not limited.
+You can accomplish this by setting up different configuration files for each
+package. See the documentation for the package manager of your choice since
+each will have its own specific files and instructions to follow to publish
+a given package.
+
+Here, we will walk through how to do this with [NPM](../npm_registry/index.md).
+
+Let us say we have a project structure like so:
+
+```plaintext
+MyProject/
+  |- src/
+  |   |- components/
+  |       |- Foo/
+  |- package.json
+```
+
+`MyProject` is the parent project, which contains a sub-project `Foo` in the
+`components` directory. We would like to publish packages for both `MyProject`
+as well as `Foo`.
+
+Following the instructions in the
+[GitLab NPM registry documentation](../npm_registry/index.md),
+publishing `MyProject` consists of modifying the `package.json` file with a
+`publishConfig` section, as well as either modifying your local NPM config with
+CLI commands like `npm config set`, or saving a `.npmrc` file in the root of the
+project specifying these config settings.
+
+If you follow the instructions you can publish `MyProject` by running
+`npm publish` from the root directory.
+
+Publishing `Foo` is almost exactly the same, you simply have to follow the steps
+while in the `Foo` directory. `Foo` will need it's own `package.json` file,
+which can be added manually or using `npm init`. And it will need it's own
+configuration settings. Since you are publishing to the same place, if you
+used `npm config set` to set the registry for the parent project, then no
+additional setup is necessary. If you used a `.npmrc` file, you will need an
+additional `.npmrc` file in the `Foo` directory (be sure to add `.npmrc` files
+to the `.gitignore` file or use environment variables in place of your access
+tokens to preven them from being exposed). It can be identical to the
+one you used in `MyProject`. You can now run `npm publish` from the `Foo`
+directory and you will be able to publish `Foo` separately from `MyProject`
+
+A similar process could be followed for Conan packages, instead of dealing with
+`.npmrc` and `package.json`, you will just be dealing with `conanfile.py` in
+multiple locations within the project.
+
+## Publishing to other projects
+
+A package is associated with a project on GitLab, but the package does not
+need to be associated with the code in that project. Notice when configuring
+NPM or Maven, you only use the `Project ID` to set the registry URL that the
+package will be uploaded to. If you set this to any project that you have
+access to and update any other config similarly depending on the package type,
+your packages will be published to that project. This means you can publish
+multiple packages to one project, even if their code does not exist in the same
+place. See the [project registry workflow documentation](./project_registry.md)
+for more details.
+
+## CI workflows for automating packaging
+
+CI pipelines open an entire world of possibilities for dealing with the patterns
+described in the previous sections. A common desire would be to publish
+specific packages only if changes were made to those directories.
+
+Using the example project above, this `gitlab-ci.yml` file will publish
+`Foo` anytime changes are made to the `Foo` directory on the `master` branch,
+and publish `MyPackage` anytime changes are made to anywhere _except_ the `Foo`
+directory on the `master` branch.
+
+```sh
+stages:
+  - build
+
+.default-rule: &default-rule
+  if: '$CI_MERGE_REQUEST_IID || $CI_COMMIT_REF_SLUG == "master"'
+
+.foo-package:
+  variables:
+    PACKAGE: "Foo"
+  before_script:
+    - cd src/components/Foo
+  only:
+    changes:
+      - "src/components/Foo/**/*"
+
+.parent-package:
+  variables:
+    PACKAGE: "MyPackage"
+  except:
+    changes:
+      - "src/components/Foo/**/*"
+
+.build-package:
+  stage: build
+  script:
+    - echo "Building $PACKAGE"
+    - npm publish
+  rules:
+    - <<: *default-rule
+
+build-foo-package:
+  extends:
+    - .build-package
+    - .foo-package
+
+build-my-project-package:
+  extends:
+    - .build-package
+    - .parent-package
+```