github.com/goreleaser/goreleaser@v1.25.1/www/docs/ci/gitlab.md (about)

     1  # GitLab CI
     2  
     3  Below are some example GitLab CI jobs that use GoReleaser to release a project.
     4  
     5  > If you are using private hosted or Enterprise version of GitLab, please follow this [guide](/scm/gitlab/) before diving into the details.
     6  
     7  ## Basic Releasing
     8  
     9  You can easily run GoReleaser in GitLab CI using its Docker container.
    10  
    11  In the repository's GitLab CI settings, add a `GITLAB_TOKEN` variable. The value should
    12  be an API token with `api` scope for a user that has access to the project. This
    13  variable should be masked and optionally protected if the job will only run on
    14  protected branches and tags.
    15  
    16  !!! warning
    17  
    18      If you use a project access token, make sure to set `use_package_registry`
    19      to `true` as well, otherwise it might not work.
    20  
    21  !!! warning
    22  
    23      If you are using a [protected variable](https://docs.gitlab.com/ee/ci/variables/#protected-cicd-variables)
    24      to store any of the values needed by goreleaser, ensure that you are protecting the tags as CI jobs in
    25      Gitlab only may access protected variables if the job is run for protected refs
    26      ([branches](https://docs.gitlab.com/ee/user/project/protected_branches.html),
    27      [tags](https://docs.gitlab.com/ee/user/project/protected_tags.html)).
    28  
    29  See [Quick Start](https://goreleaser.com/quick-start/) for more information on
    30  GoReleaser's environment variables.
    31  
    32  Add a `.gitlab-ci.yml` file to the root of the project:
    33  
    34  ```yaml
    35  stages:
    36    - release
    37  
    38  release:
    39    stage: release
    40    image:
    41      name: goreleaser/goreleaser
    42      entrypoint: [""]
    43    only:
    44      - tags
    45    variables:
    46      # Disable shallow cloning so that goreleaser can diff between tags to
    47      # generate a changelog.
    48      GIT_DEPTH: 0
    49    script:
    50      - goreleaser release --clean
    51  ```
    52  
    53  Notice that `entrypoint` is intentionally blank. See the
    54  [GitLab documentation on entrypoints](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#overriding-the-entrypoint-of-an-image)
    55  for more information.
    56  
    57  When tags are pushed to the repository,
    58  an available GitLab Runner with the Docker executor will pick up the release job.
    59  `goreleaser/goreleaser` will start in a container, and the repository will be mounted inside.
    60  Finally, the `script` section will run within the container starting in your project's directory.
    61  
    62  ## Releasing Archives and Pushing Images
    63  
    64  Pushing images to a registry requires using Docker-in-Docker. To create GitLab releases and push
    65  images to a Docker registry, add a file `.gitlab-ci.yml` to the root of the project:
    66  
    67  ```yaml
    68  stages:
    69    - release
    70  
    71  release:
    72    stage: release
    73    image: docker:stable
    74    services:
    75      - docker:dind
    76  
    77    variables:
    78      # Optionally use GitLab's built-in image registry.
    79      # DOCKER_REGISTRY: $CI_REGISTRY
    80      # DOCKER_USERNAME: $CI_REGISTRY_USER
    81      # DOCKER_PASSWORD: $CI_REGISTRY_PASSWORD
    82  
    83      # Or, use any registry, including the official one.
    84      DOCKER_REGISTRY: https://index.docker.io/v1/
    85  
    86      # Disable shallow cloning so that goreleaser can diff between tags to
    87      # generate a changelog.
    88      GIT_DEPTH: 0
    89  
    90    # Only run this release job for tags, not every commit (for example).
    91    only:
    92      refs:
    93        - tags
    94  
    95    script: |
    96      # GITLAB_TOKEN is needed to create GitLab releases.
    97      # CI_JOB_TOKEN is needed if use_job_token is set.
    98      # DOCKER_* are needed to push Docker images.
    99      docker run --rm --privileged \
   100        -v $PWD:/go/src/gitlab.com/YourGitLabUser/YourGitLabRepo \
   101        -w /go/src/gitlab.com/YourGitLabUser/YourGitLabRepo \
   102        -v /var/run/docker.sock:/var/run/docker.sock \
   103        -e DOCKER_USERNAME \
   104        -e DOCKER_PASSWORD \
   105        -e DOCKER_REGISTRY \
   106        -e GITLAB_TOKEN \
   107        -e CI_JOB_TOKEN \
   108        goreleaser/goreleaser release --clean
   109  ```
   110  
   111  In GitLab CI settings, add variables for `DOCKER_REGISTRY`, `DOCKER_USERNAME`,
   112  and `DOCKER_PASSWORD` if you aren't using the GitLab image registry. If you are
   113  using the GitLab image registry, you don't need to set these.
   114  
   115  Add a variable `GITLAB_TOKEN` if you are using [GitLab
   116  releases](https://docs.gitlab.com/ce/user/project/releases/). The value should
   117  be an API token with `api` scope for a user that has access to the project.
   118  
   119  Alternatively, you can provide the gitlab token in a file. GoReleaser will check
   120  `~/.config/goreleaser/gitlab_token` by default, but you can change that in the
   121  `.goreleaser.yaml` file:
   122  
   123  ```yaml
   124  # .goreleaser.yaml
   125  env_files:
   126    gitlab_token: ~/.path/to/my/gitlab_token
   127  ```
   128  
   129  Note that the environment variable will be used if available, regardless of the
   130  `gitlab_token` file.
   131  
   132  The secret variables, `DOCKER_PASSWORD` and `GITLAB_TOKEN`, should be masked.
   133  Optionally, you might want to protect them if the job that uses them will only
   134  be run on protected branches or tags.
   135  
   136  Make sure the `image_templates` in the file `.goreleaser.yaml` reflect that
   137  custom registry!
   138  
   139  Example:
   140  
   141  ```yaml
   142  dockers:
   143    - goos: linux
   144      goarch: amd64
   145      image_templates:
   146        - "registry.gitlab.com/Group/Project:{{ .Tag }}"
   147        - "registry.gitlab.com/Group/Project:latest"
   148  ```
   149  
   150  ## Example Repository
   151  
   152  You can check [this example repository](https://gitlab.com/goreleaser/example) for a real world example.
   153  
   154  <a href="https://gitlab.com/goreleaser/example/-/releases">
   155    <figure>
   156      <img src="https://img.carlosbecker.dev/goreleaser-gitlab.png"/>
   157      <figcaption>Example release on GitLab.</figcaption>
   158    </figure>
   159  </a>