Docs

# Initiate a stacks branch with a basic pipeline

Pipeline step2

As described in Concepts of a stack, we start by creating a stack. Create a stacks branch containing our stack directory that we will call stack-sample and put a hello world pipeline template in it. Then add a description of our stack in a .cycloid.yml file.

Follow those steps to apply all changes described in this step

# Cycloid.yml

Each stack has to contain a .cycloid.yml file, which describes global information about a stack such as a name, the icon, ansible/terraform paths, etc.

# Readme.md (optional)

To provide detailed information and documentation about your stack (goal, requirements, usage), you can add a README.md file in Markdown format. The content of this file will be visible by the users in the Cycloid console as part of the stack details page.

Having a README will display detailed information about your stack for others to understand what it is about.

# Pipeline

A pipeline is composed of 2 files. A pipeline template file (pipeline.yml) and an example of variables file (variables.sample.yml) used for the templating using the ((variable_name)) format.

stack-sample/pipeline/pipeline.yml








 






 




 

 


















groups:
- name: overview
  jobs:
  - unittest

resources:

- name: git_code
  type: git
  source:
    uri: ((code_git_public_repository))
    branch: ((code_git_branch))

jobs:
  - name: unittest
    max_in_flight: 1
    build_logs_to_retain: 10
    plan:
    - do:
      - get: git_code
        trigger: true
      - task: test
        config:
          platform: linux
          image_resource:
            type: docker-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: latest
          run:
            path: /bin/bash
            args:
            - -ec
            - |
              echo "Testing the application"
              ls code
          inputs:
          - name: git_code
            path: code
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

Due to the CI/CD solution named Concourse (opens new window) and used by Cycloid for running pipelines, it's essential to know that a pipeline results from configuring Jobs and Resources together.

In our example, we defined a resource of type git named git_code and a job named unittest. Each job have to be part of a group, it will create a group view on Cycloid console to display pipeline jobs.

git_code: is a resource (opens new window) to define a Git repository. This resource will trigger the job to test the code when the repository is updated.

unittest: is a job (opens new window). It describes the steps needed to complete a job. In our case we need to get our website source code, then run tests. The usual steps are:

  • get step: Fetches a resource, making it available to subsequent tasks via the given name.
  • put step: Pushes to the given resource. For example, for the git resource, a push would git commit/push into the repository.
  • task step: Executes a Task with inline configuration.

TIPS

Resources and tasks are based on Docker images. It's really flexible and allows you to provide your own environment or required tools. If you are interested in implementing your own resource, please follow https://concourse-ci.org/implementing-resource-types.html (opens new window) documentation.

This unittest job get the source code of our website using the git_code resource (see line 20), then runs a task to test our website source code. (line 22). This test actually just lists files but you usually should put the real commands to test your application source code.

WARNING

inputs and outputs are volumes exposed to/from a task with others steps. In our case, we say that our task requires the content of the git_code resource as input in the directory code.

If you want to know more about pipelines, you can read our Pipeline guide and the Concourse (opens new window) documentation.

# Variables sample

The variables sample file is used as an example when you create a project using Cycloid's dashboard.

stack-sample/pipeline/variables.sample.yml






 


env: ($ environment $)
project: ($ project $)
customer: ($ organization_canonical $)

# Code repo configuration
code_git_public_repository: https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git
code_git_branch: code
1
2
3
4
5
6
7

The format of this file is pretty simple, key: value. But there are 2 specificities:

  • The first 3 lines are Cycloid special variables automatically provided when you create a project.
  • Line 6 contains a regular string variable, in our case the URL of the git repository to use for our website source code.

# Key points to remember

  • Each stack has to contain a .cycloid.yml file
  • To provide detailed information and documentation about your stack (goal, requirements, usage), you can add a README.md file in Markdown format
  • A pipeline is composed of 2 files. A pipeline template file (pipeline.yml) and an example of variables file (variables.sample.yml) used for the templating using the ((variable_name)) format
  • The variables sample file is used as an example when you create a project using Cycloid's dashboard
  • A pipeline contain Jobs and Resources

← Step 2 part 2 - Use a stack →