-
Notifications
You must be signed in to change notification settings - Fork 18
/
999-gocd-migration.md.erb
71 lines (51 loc) · 5.61 KB
/
999-gocd-migration.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
---
title: Migration to GoCD
doc_title: Migration to GoCD
---
For those users interested in using [GoCD](https://www.gocd.io/) after Snap CI goes away we can provide an export of your Snap configuration in a format that GoCD will understand to ease your migration to GoCD. [Get in touch with us](<%= data.links.contact_us %>) and provide the repository name and branch that you’d like the GoCD configuration for and we will gladly provide that for you.
The following information explains how to use the export we will provide for you.
## Prerequisites to use
* Follow the [quick start guide to GoCD](https://www.gocd.io/getting-started/part-1/) to learn key concepts in GoCD and get setup quickly
* [Install GoCD server](https://docs.gocd.io/current/installation/)
* [Install at least one GoCD agent](https://docs.gocd.io/current/installation/)
* We recommend creating a simple pipeline following the [quick start guide to GoCD](https://www.gocd.io/getting-started/part-1/)
## Limitations
The pipeline configuration that is generated is not meant to be a 100% working copy of a GoCD pipeline. It is only meant to get you started.
What is does:
* Creates a pipeline
* Creates a [timer trigger](https://docs.gocd.io/current/configuration/admin_timer.html) for scheduled builds (see limitations below)
* Converts Snap CI pinned environment variables into GoCD pipeline variables
* Generates Git [material](https://docs.gocd.io/current/introduction/concepts_in_go.html#materials) with placeholder username and password
* Creates stages and [jobs](https://docs.gocd.io/current/introduction/concepts_in_go.html#job)(a job shares the stage name). There is one job per stage
* Converts Snap CI stage variables into GoCD stage variables
* Converts Snap CI tasks into GoCD tasks (‘bash -c “whatever snap command you had”’ is used)
* Converts Snap CI artifacts into GoCD artifacts
What it does not do:
* Does not create a pipeline group
* Does not create [timer trigger](https://docs.gocd.io/current/configuration/admin_timer.html) for all scenarios supported in Snap CI. The cron syntax is slightly different between Snap CI and GoCD. Specifically, support for specifying both a day-of-week AND a day-of-month parameter is not supported in GoCD and will result in an error. Please edit your config accordingly to meet GoCDs requirements)
* Does not create individual jobs from parallel Snap CI jobs
* Does not export secure environment variable values
* Does not export secure file contents
## Notes on artifacts
The exported GoCD configuration attempts to be as close as possible to the behavior of pipelines in Snap CI. It should be correct in most cases. However, we have made some simplifying assumptions when exporting pipelines.
* The GoCD config contains all artifacts you declare in each stage along with instructions to propagate these artifacts. These instructions appear as “fetchartifact” tasks in the subsequent stages.
* Any artifact with a period in the name is assumed to be a file artifact and is fetched using the fetchartifact task with a “srcfile” attribute. If this is incorrect, you may need to change the srcfile to a srcdir attribute.
* For assumed file artifacts, we also attempt to locate the destination to be the path up to the last fragment in the artifact name. You may need to tweak this if you expect the artifact to be placed elsewhere on your filesystem.
* Any artifact without a period in the name is assumed to be a directory artifact and is fetched using the fetchartifact task with a “srcfdir” attribute. If this is incorrect, you may need to change the srcdir to a srcfile attribute.
## Instructions to use
* On your GoCD server, edit the config.xml (typically under: /go/admin/config_xml) or via the UI at: /go/admin/pipelines/PIPELINE_NAME/general
* Place the generated configuration in the pipelines section of the xml
* You may want to edit the pipeline name to better reflect your naming conventions
* Edit the git URL generated and put in a valid Github username and password in place of the USERNAME:PASSWORD placeholder text. (You may also alter this to use SSH authentication)
* Save your configuration
* If the Go server is new without any prior pipelines created then you may get the following error `Invalid content was found starting with element 'pipeline'. One of '{repositories, scms, config-repos, pipelines, templates, environments, agents}' is expected.` To resolve this either create a pipeline group prior to using the Snap CI generated config.xml or add `<pipelines group="defaultGroup">` to the start of the config and `</pipelines>` to the end.
* Edit the values of secure variables
* Once the configuration is saved navigate to the pipeline config UI. This is usually at: /go/admin/pipelines/PIPELINE_NAME/general
* For pinned environment variables, select the pipeline name in the sidebar and in the environment variables tab on the right, put in the value for the secure environment variables that you had in Snap CI. These variables will be available in every stage of your pipeline
* For stage level environment variables, select the stage name under the pipeline in the sidebar and edit the environment variables in the tab on the right. These environment variables will only be available in this stage
* You may also need to edit your deployment stages as the snap-deploy tool is not available in Go
* Save the configuration once again
* Navigate to the dashboard
* Unpause the pipeline if it is marked as “under construction” and click the “play” button to trigger the first run
* Your build should now run as it did in Snap CI!
If you need any help using this please [get in touch with us](<%= data.links.contact_us %>).