Refactor build artifacts documentation
- Split user and admin documentation - Use new location paths - Add new Continuous Integration guide for the Admin area - Link to new guide from the Admin area
This commit is contained in:
Achilleas Pipinellis
parent
95e5b4634d
commit
c3ed78a4ed
14 changed files with 222 additions and 176 deletions
|
|
@ -228,6 +228,9 @@
|
|||
= f.label :max_artifacts_size, 'Maximum artifacts size (MB)', class: 'control-label col-sm-2'
|
||||
.col-sm-10
|
||||
= f.number_field :max_artifacts_size, class: 'form-control'
|
||||
.help-block
|
||||
Set the maximum file size each build's artifacts can have
|
||||
= link_to "(?)", help_page_path("user/admin_area/settings/continuous_integration", anchor: "maximum-artifacts-size")
|
||||
|
||||
- if Gitlab.config.registry.enabled
|
||||
%fieldset
|
||||
|
|
@ -385,4 +388,4 @@
|
|||
|
||||
|
||||
.form-actions
|
||||
= f.submit 'Save', class: 'btn btn-save'
|
||||
= f.submit 'Save', class: 'btn btn-save'
|
||||
|
|
|
|||
90
doc/administration/build_artifacts.md
Normal file
90
doc/administration/build_artifacts.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
# Build artifacts administration
|
||||
|
||||
>**Notes:**
|
||||
>- Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
|
||||
>- Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
|
||||
changed to `ZIP`.
|
||||
>- This is the administration documentation. For the user guide see
|
||||
[user/project/builds/artifacts.md](../user/project/builds/artifacts.md).
|
||||
|
||||
Artifacts is a list of files and directories which are attached to a build
|
||||
after it completes successfully. This feature is enabled by default in all
|
||||
GitLab installations. Keep reading if you want to know how to disable it.
|
||||
|
||||
## Disabling build artifacts
|
||||
|
||||
To disable artifacts site-wide, follow the steps below.
|
||||
|
||||
---
|
||||
|
||||
**In Omnibus installations:**
|
||||
|
||||
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['artifacts_enabled'] = false
|
||||
```
|
||||
|
||||
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
|
||||
|
||||
---
|
||||
|
||||
**In installations from source:**
|
||||
|
||||
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
|
||||
|
||||
```yaml
|
||||
artifacts:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
1. Save the file and [restart GitLab][] for the changes to take effect.
|
||||
|
||||
## Storing build artifacts
|
||||
|
||||
After a successful build, GitLab Runner uploads an archive containing the build
|
||||
artifacts to GitLab.
|
||||
|
||||
To change the location where the artifacts are stored, follow the steps below.
|
||||
|
||||
---
|
||||
|
||||
**In Omnibus installations:**
|
||||
|
||||
_The artifacts are stored by default in
|
||||
`/var/opt/gitlab/gitlab-rails/shared/artifacts`._
|
||||
|
||||
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
|
||||
`/etc/gitlab/gitlab.rb` and add the following line:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
|
||||
```
|
||||
|
||||
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
|
||||
|
||||
---
|
||||
|
||||
**In installations from source:**
|
||||
|
||||
_The artifacts are stored by default in
|
||||
`/home/git/gitlab/shared/artifacts`._
|
||||
|
||||
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
|
||||
`/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
|
||||
|
||||
```yaml
|
||||
artifacts:
|
||||
enabled: true
|
||||
path: /mnt/storage/artifacts
|
||||
```
|
||||
|
||||
1. Save the file and [restart GitLab][] for the changes to take effect.
|
||||
|
||||
## Set the maximum file size of the artifacts
|
||||
|
||||
Provided the artifacts are enabled, you can change the maximum file size of the
|
||||
artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration#maximum-artifacts-size).
|
||||
|
||||
[reconfigure gitlab]: restart_gitlab.md "How to restart GitLab"
|
||||
[restart gitlab]: restart_gitlab.md "How to restart GitLab"
|
||||
|
|
@ -14,7 +14,7 @@
|
|||
- [Use variables in your `.gitlab-ci.yml`](variables/README.md)
|
||||
- [Use SSH keys in your build environment](ssh_keys/README.md)
|
||||
- [Trigger builds through the API](triggers/README.md)
|
||||
- [Build artifacts](build_artifacts/README.md)
|
||||
- [Build artifacts](../user/project/builds/artifacts.md)
|
||||
- [User permissions](../user/permissions.md#gitlab-ci)
|
||||
- [API](../api/ci/README.md)
|
||||
- [CI services (linked docker containers)](services/README.md)
|
||||
|
|
|
|||
|
|
@ -1,175 +1,4 @@
|
|||
# Introduction to build artifacts
|
||||
This document was moved to:
|
||||
|
||||
Artifacts is a list of files and directories which are attached to a build
|
||||
after it completes successfully. This feature is enabled by default in all GitLab installations.
|
||||
|
||||
_If you are searching for ways to use artifacts, jump to
|
||||
[Defining artifacts in `.gitlab-ci.yml`](#defining-artifacts-in-gitlab-ciyml)._
|
||||
|
||||
Since GitLab 8.2 and [GitLab Runner] 0.7.0, build artifacts that are created by
|
||||
GitLab Runner are uploaded to GitLab and are downloadable as a single archive
|
||||
(`tar.gz`) using the GitLab UI.
|
||||
|
||||
Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
|
||||
changed to `ZIP`, and it is now possible to browse its contents, with the added
|
||||
ability of downloading the files separately.
|
||||
|
||||
**Note:**
|
||||
The artifacts browser will be available only for new artifacts that are sent
|
||||
to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
|
||||
browse old artifacts already uploaded to GitLab.
|
||||
|
||||
## Disabling build artifacts
|
||||
|
||||
To disable artifacts site-wide, follow the steps below.
|
||||
|
||||
---
|
||||
|
||||
**In Omnibus installations:**
|
||||
|
||||
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['artifacts_enabled'] = false
|
||||
```
|
||||
|
||||
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
|
||||
|
||||
---
|
||||
|
||||
**In installations from source:**
|
||||
|
||||
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
|
||||
|
||||
```yaml
|
||||
artifacts:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
1. Save the file and [restart GitLab][] for the changes to take effect.
|
||||
|
||||
## Defining artifacts in `.gitlab-ci.yml`
|
||||
|
||||
A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
|
||||
the following:
|
||||
|
||||
```yaml
|
||||
pdf:
|
||||
script: xelatex mycv.tex
|
||||
artifacts:
|
||||
paths:
|
||||
- mycv.pdf
|
||||
```
|
||||
|
||||
A job named `pdf` calls the `xelatex` command in order to build a pdf file from
|
||||
the latex source file `mycv.tex`. We then define the `artifacts` paths which in
|
||||
turn are defined with the `paths` keyword. All paths to files and directories
|
||||
are relative to the repository that was cloned during the build.
|
||||
|
||||
For more examples on artifacts, follow the
|
||||
[separate artifacts yaml documentation](../yaml/README.md#artifacts).
|
||||
|
||||
## Storing build artifacts
|
||||
|
||||
After a successful build, GitLab Runner uploads an archive containing the build
|
||||
artifacts to GitLab.
|
||||
|
||||
To change the location where the artifacts are stored, follow the steps below.
|
||||
|
||||
---
|
||||
|
||||
**In Omnibus installations:**
|
||||
|
||||
_The artifacts are stored by default in
|
||||
`/var/opt/gitlab/gitlab-rails/shared/artifacts`._
|
||||
|
||||
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
|
||||
`/etc/gitlab/gitlab.rb` and add the following line:
|
||||
|
||||
```ruby
|
||||
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
|
||||
```
|
||||
|
||||
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
|
||||
|
||||
---
|
||||
|
||||
**In installations from source:**
|
||||
|
||||
_The artifacts are stored by default in
|
||||
`/home/git/gitlab/shared/artifacts`._
|
||||
|
||||
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
|
||||
`/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
|
||||
|
||||
```yaml
|
||||
artifacts:
|
||||
enabled: true
|
||||
path: /mnt/storage/artifacts
|
||||
```
|
||||
|
||||
1. Save the file and [restart GitLab][] for the changes to take effect.
|
||||
|
||||
## Browsing build artifacts
|
||||
|
||||
When GitLab receives an artifacts archive, an archive metadata file is also
|
||||
generated. This metadata file describes all the entries that are located in the
|
||||
artifacts archive itself. The metadata file is in a binary format, with
|
||||
additional GZIP compression.
|
||||
|
||||
GitLab does not extract the artifacts archive in order to save space, memory
|
||||
and disk I/O. It instead inspects the metadata file which contains all the
|
||||
relevant information. This is especially important when there is a lot of
|
||||
artifacts, or an archive is a very large file.
|
||||
|
||||
---
|
||||
|
||||
After a successful build, if you visit the build's specific page, you can see
|
||||
that there are two buttons.
|
||||
|
||||
One is for downloading the artifacts archive and the other for browsing its
|
||||
contents.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
The archive browser shows the name and the actual file size of each file in the
|
||||
archive. If your artifacts contained directories, then you are also able to
|
||||
browse inside them.
|
||||
|
||||
Below you can see an image of three different file formats, as well as two
|
||||
directories.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Downloading build artifacts
|
||||
|
||||
If you need to download the whole archive, there are buttons in various places
|
||||
inside GitLab that make that possible.
|
||||
|
||||
1. While on the builds page, you can see the download icon for each build's
|
||||
artifacts archive in the right corner
|
||||
|
||||
1. While inside a specific build, you are presented with a download button
|
||||
along with the one that browses the archive
|
||||
|
||||
1. And finally, when browsing an archive you can see the download button at
|
||||
the top right corner
|
||||
|
||||
---
|
||||
|
||||
Note that GitLab does not extract the entire artifacts archive to send just a
|
||||
single file to the user.
|
||||
|
||||
When clicking on a specific file, [GitLab Workhorse] extracts it from the
|
||||
archive and the download begins.
|
||||
|
||||
This implementation saves space, memory and disk I/O.
|
||||
|
||||
[gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner "GitLab Runner repository"
|
||||
[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
|
||||
[restart gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
|
||||
[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
|
||||
- [user/project/builds/artifacts.md](../user/project/builds/artifacts.md) - user guide
|
||||
- [administration/build_artifacts.md](../administration/build_artifacts.md) - administrator guide
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 80 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 7.1 KiB |
20
doc/user/admin_area/settings/continuous_integration.md
Normal file
20
doc/user/admin_area/settings/continuous_integration.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# Continuous integration Admin settings
|
||||
|
||||
## Maximum artifacts size
|
||||
|
||||
The maximum size of the [build artifacts][art-yml] can be set in the Admin area
|
||||
of your GitLab instance. The value is in MB and the default is 100MB. Note that
|
||||
this setting is set for each build.
|
||||
|
||||
1. Go to **Admin area > Settings** (`/admin/application_settings`).
|
||||
|
||||
|
||||
|
||||
1. Change the value of the maximum artifacts size (in MB):
|
||||
|
||||
|
||||
|
||||
1. Hit **Save** for the changes to take effect.
|
||||
|
||||
|
||||
[art-yml]: ../../../administration/build_artifacts.md
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 6.1 KiB |
BIN
doc/user/admin_area/settings/img/admin_area_settings_button.png
Normal file
BIN
doc/user/admin_area/settings/img/admin_area_settings_button.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9 KiB |
104
doc/user/project/builds/artifacts.md
Normal file
104
doc/user/project/builds/artifacts.md
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
# Introduction to build artifacts
|
||||
|
||||
>**Notes:**
|
||||
>- Since GitLab 8.2 and GitLab Runner 0.7.0, build artifacts that are created by
|
||||
GitLab Runner are uploaded to GitLab and are downloadable as a single archive
|
||||
(`tar.gz`) using the GitLab UI.
|
||||
>- Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
|
||||
changed to `ZIP`, and it is now possible to browse its contents, with the added
|
||||
ability of downloading the files separately.
|
||||
>- The artifacts browser will be available only for new artifacts that are sent
|
||||
to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
|
||||
browse old artifacts already uploaded to GitLab.
|
||||
>- This is the user documentation. For the administration guide see
|
||||
[administration/build_artifacts.md](../../../administration/build_artifacts.md).
|
||||
|
||||
Artifacts is a list of files and directories which are attached to a build
|
||||
after it completes successfully. This feature is enabled by default in all GitLab installations.
|
||||
|
||||
## Defining artifacts in `.gitlab-ci.yml`
|
||||
|
||||
A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
|
||||
the following:
|
||||
|
||||
```yaml
|
||||
pdf:
|
||||
script: xelatex mycv.tex
|
||||
artifacts:
|
||||
paths:
|
||||
- mycv.pdf
|
||||
```
|
||||
|
||||
A job named `pdf` calls the `xelatex` command in order to build a pdf file from
|
||||
the latex source file `mycv.tex`. We then define the `artifacts` paths which in
|
||||
turn are defined with the `paths` keyword. All paths to files and directories
|
||||
are relative to the repository that was cloned during the build.
|
||||
|
||||
For more examples on artifacts, follow the artifacts reference in
|
||||
[`.gitlab-ci.yml` documentation](../../../ci/yaml/README.md#artifacts).
|
||||
|
||||
## Browsing build artifacts
|
||||
|
||||
When GitLab receives an artifacts archive, an archive metadata file is also
|
||||
generated. This metadata file describes all the entries that are located in the
|
||||
artifacts archive itself. The metadata file is in a binary format, with
|
||||
additional GZIP compression.
|
||||
|
||||
GitLab does not extract the artifacts archive in order to save space, memory
|
||||
and disk I/O. It instead inspects the metadata file which contains all the
|
||||
relevant information. This is especially important when there is a lot of
|
||||
artifacts, or an archive is a very large file.
|
||||
|
||||
---
|
||||
|
||||
After a build finishes, if you visit the build's specific page, you can see
|
||||
that there are two buttons. One is for downloading the artifacts archive and
|
||||
the other for browsing its contents.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
The archive browser shows the name and the actual file size of each file in the
|
||||
archive. If your artifacts contained directories, then you are also able to
|
||||
browse inside them.
|
||||
|
||||
Below you can see how browsing looks like. In this case we have browsed inside
|
||||
the archive and at this point there is one directory and one HTML file.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Downloading build artifacts
|
||||
|
||||
>**Note:**
|
||||
GitLab does not extract the entire artifacts archive to send just a single file
|
||||
to the user. When clicking on a specific file, [GitLab Workhorse] extracts it
|
||||
from the archive and the download begins. This implementation saves space,
|
||||
memory and disk I/O.
|
||||
|
||||
If you need to download the whole archive, there are buttons in various places
|
||||
inside GitLab that make that possible.
|
||||
|
||||
1. While on the pipelines page, you can see the download icon for each build's
|
||||
artifacts archive in the right corner:
|
||||
|
||||
|
||||
|
||||
1. While on the builds page, you can see the download icon for each build's
|
||||
artifacts archive in the right corner:
|
||||
|
||||
|
||||
|
||||
1. While inside a specific build, you are presented with a download button
|
||||
along with the one that browses the archive:
|
||||
|
||||
|
||||
|
||||
1. And finally, when browsing an archive you can see the download button at
|
||||
the top right corner:
|
||||
|
||||
|
||||
|
||||
[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
|
||||
BIN
doc/user/project/builds/img/build_artifacts_browser.png
Normal file
BIN
doc/user/project/builds/img/build_artifacts_browser.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 8.2 KiB |
BIN
doc/user/project/builds/img/build_artifacts_browser_button.png
Normal file
BIN
doc/user/project/builds/img/build_artifacts_browser_button.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
BIN
doc/user/project/builds/img/build_artifacts_builds_page.png
Normal file
BIN
doc/user/project/builds/img/build_artifacts_builds_page.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
BIN
doc/user/project/builds/img/build_artifacts_pipelines_page.png
Normal file
BIN
doc/user/project/builds/img/build_artifacts_pipelines_page.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
Loading…
Reference in a new issue