Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
13e170cc
Commit
13e170cc
authored
Jun 23, 2020
by
Shinya Maeda
Committed by
Marcel Amirault
Jun 23, 2020
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
GitLab CI templates Development Guideline
This commit adds a guideline for template development
parent
cc687bc8
Changes
4
Hide whitespace changes
Inline
Side-by-side
Showing
4 changed files
with
71 additions
and
0 deletions
+71
-0
doc/development/cicd/img/ci_template_selection_v13_1.png
doc/development/cicd/img/ci_template_selection_v13_1.png
+0
-0
doc/development/cicd/index.md
doc/development/cicd/index.md
+2
-0
doc/development/cicd/templates.md
doc/development/cicd/templates.md
+66
-0
lib/gitlab/ci/templates/index.md
lib/gitlab/ci/templates/index.md
+3
-0
No files found.
doc/development/cicd/img/ci_template_selection_v13_1.png
0 → 100644
View file @
13e170cc
20.8 KB
doc/development/cicd/index.md
View file @
13e170cc
...
...
@@ -2,6 +2,8 @@
Development guides that are specific to CI/CD are listed here.
If you are creating new CI/CD templates, please read
[
the development guide for GitLab CI/CD templates
](
templates.md
)
.
## CI Architecture overview
The following is a simplified diagram of the CI architecture. Some details are left out in order to focus on
...
...
doc/development/cicd/templates.md
0 → 100644
View file @
13e170cc
# Development guide for GitLab CI/CD templates
This document explains how to develop
[
GitLab CI/CD templates
](
../../ci/examples/README.md
)
.
## Place the template file in a relevant directory
All template files reside in the
`lib/gitlab/ci/templates`
directory, and are categorized by the following sub-directories:
| Sub-directroy | Content |
[
Selectable in UI
](
#make-sure-the-new-template-can-be-selected-in-ui
)
|
|---------------|--------------------------------------------------------------|-----------------------------------------------------------------------|
|
`/Jobs/*`
| Auto DevOps related jobs | Yes |
|
`/Pages/*`
| Static site generators for GitLab Pages (for example Jekyll) | Yes |
|
`/Security/*`
| Security related jobs | Yes |
|
`/Verify/*`
| Verify/testing related jobs | Yes |
|
`/Worklows/*`
| Common uses of the
`workflow:`
keyword | No |
|
`/*`
(root) | General templates | Yes |
## Criteria
The file must follow the
[
`.gitlab-ci.yml` syntax
](
../../ci/yaml/README.md
)
.
Verify it's valid by pasting it into the
[
CI lint tool
](
https://gitlab.com/gitlab-org/gitlab/-/ci/lint
)
.
Also, all templates must be named with the
`*.gitlab-ci.yml`
suffix.
### Backward compatibility
A template might be dynamically included with the
`include:template:`
keyword. If
you make a change to an
*existing*
template, you must make sure that it won't break
CI/CD in existing projects.
## Testing
Each CI/CD template must be tested in order to make sure that it's safe to be published.
### Manual QA
It's always good practice to test the template in a minimal demo project.
To do so, please follow the following steps:
1.
Create a public sample project on
<http://gitlab.com>
.
1.
Add a
`.gitlab-ci.yml`
to the project with the proposed template.
1.
Run pipelines and make sure that everything runs properly, in all possible cases
(merge request pipelines, schedules, and so on).
1.
Link to the project in the description of the merge request that is adding a new template.
This is useful information for reviewers to make sure the template is safe to be merged.
### Make sure the new template can be selected in UI
Templates located under some directories are also
[
selectable in the **New file** UI
](
#place-the-template-file-in-a-relevant-directory
)
.
When you add a template into one of those directories, make sure that it correctly appears in the dropdown:
![
CI/CD template selection
](
img/ci_template_selection_v13_1.png
)
### Write an RSpec test
You should write an RSpec test to make sure that pipeline jobs will be generated correctly:
1.
Add a test file at
`spec/lib/gitlab/ci/templates/<template-category>/<template-name>_spec.rb`
1.
Test that pipeline jobs are properly created via
`Ci::CreatePipelineService`
.
## Security
A template could contain malicious code. For example, a template that contains the
`export`
shell command in a job
might accidentally expose project secret variables in a job log.
If you're unsure if it's secure or not, you need to ask security experts for cross-validation.
lib/gitlab/ci/templates/index.md
0 → 100644
View file @
13e170cc
# Development guide for GitLab CI templates
Please follow
[
the development guideline
](
../../../../doc/development/cicd/templates.md
)
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment