From 0e689b414a133d9835e2ef9fa9d5b5f34e1105fd Mon Sep 17 00:00:00 2001
From: Ted Tramonte <ted.tramonte+github@gmail.com>
Date: Fri, 19 Mar 2021 07:54:34 -0400
Subject: [PATCH] docs: expand GitLab CI examples (#2122)

Docker-in-Docker is overkill for simple binary and archive release purposes. This change adds an example `.gitlab-ci.yml` and some additional explanation on the general GitLab CI process.
---
 www/docs/ci/gitlab.md | 51 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/www/docs/ci/gitlab.md b/www/docs/ci/gitlab.md
index 0e8376449..fa7cca297 100644
--- a/www/docs/ci/gitlab.md
+++ b/www/docs/ci/gitlab.md
@@ -1,7 +1,52 @@
 # GitLab CI
 
-To create GitLab releases and push images to a Docker registry, add a file
-`.gitlab-ci.yml` to the root of the project:
+Below are some example GitLab CI jobs that use GoReleaser to release a project. 
+
+## Basic Releasing
+
+You can easily run GoReleaser in GitLab CI using its Docker container. 
+
+In the repository's GitLab CI settings, add a `GITLAB_TOKEN` variable. The value should
+be an API token with `api` scope for a user that has access to the project. This
+variable should be masked and optionally protected if the job will only run on
+protected branches and tags.
+See [Quick Start](https://goreleaser.com/quick-start/) for more information on 
+GoReleaser's environment variables.
+
+Add a `.gitlab-ci.yml` file to the root of the project:
+
+```yaml
+stages:
+  - release
+
+release:
+  stage: release
+  image:
+    name: goreleaser/goreleaser
+    entrypoint: ['']
+  only:
+    - tags
+  variables:
+    # Disable shallow cloning so that goreleaser can diff between tags to
+    # generate a changelog.
+    GIT_DEPTH: 0
+  script:
+    - goreleaser release --rm-dist
+```
+
+Notice that `entrypoint` is intentionally blank. See the 
+[GitLab documentation on entrypoints](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#overriding-the-entrypoint-of-an-image) 
+for more information.
+
+When tags are pushed to the repository, 
+an available GitLab Runner with the Docker executor will pick up the release job. 
+`goreleaser/goreleaser` will start in a container and the repository will be mounted inside. 
+Finally, the `script` section will run within the container starting in your project's directory. 
+
+## Releasing Archives and Pushing Images
+
+Pushing images to a registry requires using Docker-in-Docker. To create GitLab releases and push 
+images to a Docker registry, add a file `.gitlab-ci.yml` to the root of the project:
 
 ```yaml
 stages:
@@ -70,7 +115,7 @@ dockers:
   - 'registry.gitlab.com/Group/Project:latest'
 ```
 
-## How does it look like?
+## Example Repository
 
 You can check [this example repository](https://gitlab.com/goreleaser/example) for a real world example.