# Stack definition

As described in concepts of stack, a stack in Cycloid is stored in a git repository. From a technical point of view for a stack to be valid in Cycloid you have to define and create a .cycloid.yml into your git repository.

This file will contain the name, description, keyword, and few other metadata which define your stack. Read more about .cycloid.yml file format.

# StackForms

To configure your stack via a user-friendly form, you'll need to create a new file at the same location as your .cycloid.yml file. This file will be the .forms.yml.

If present, the editor view for the project configuration will be replaced by StackForms, which takes a more visual approach, using widgets, hints, dropdowns, etc. Please note that when you're using StackForms, only a subset of elements might be configurable (depending on what was defined in the file) and that StackForms cannot be used to edit the pipeline (only the variables).


# Private stack structure

A private stack is defined by at least one .cycloid.yml file and one pipeline (pipeline.yml). Those files have to be put in a git repository which can be private or public.

To store the configuration of all your private stacks we usually use the same git repository with a dedicated branch named config. You can, however, provide a dedicated git repository for each config.

In a git repository you can create one or several stacks: one at the root level or several stacks in subdirectories (maxdepth 1). Those stacks can be created in a branch of your choice, might it be named stacks or whatever you prefer the most.

So, in the end, for private stacks you need to create a git repository containing a "config" branch to store the configuration files and a secondary "stacks" branch to store the stacks.

git clone -b <config> git@github.com:<repository name>.git <config>
git clone -b <stacks> git@github.com:<repository name>.git <stacks>

In the stacks branch you should find at the top level the names of stacks. For example stack-infrastructure, stack-myApp, ...

In those stacks, you might have 3 directories and 2 files:

  • Terraform: contains Terraform module definition (Terraform Modules (opens new window)), required variables and output of the stack
  • Ansible: default variables, roles and Ansible playbook to use
  • Pipeline: template of the pipeline used only once at the project creation step. Concourse Triggers Docs (opens new window)
  • .cycloid.yml: a file containing the description and the configuration of the stack in the catalog. Format of .cycloid.yml file
  • README.md: a file in a markdown format where you usually write stack usage documentation. The name of the file is not case sensitive, you can use different name such as readme.md, Readme.md, ...
  • .forms.yml: a file containing the description of widgets to be used by StackForms Format of .forms.yml file

Here is an example of the stack-myApp folder:

├── ansible
│   └── site.yml
├── .cycloid.yml
├── .forms.yml
├── pipeline
│   ├── pipeline.yml
│   └── variables.sample.yml
├── README.md
└── terraform
    └── provider.tf

3 directories, 7 files

In the config branch you might find at the top level, a name of a Cycloid project that use a stack. For example infrastructure, myProject, ...

  • Terraform: the call of the module defined in the stack. The call contains all configuration variable of the module. You can imagine stack like a function definition and config like a call of that function specifying args
  • Ansible: contains usually variable file used by the playbook defined in the stack

Here is an example of a myProject folder in a config branch:

├── ansible
│   └── prod-variables.yml
└── terraform
    └── prod
        └── variables.tf

3 directories, 2 files

# Creating and updating a catalog repository

Like creating and updating a config repository, creating or updating the catalog repository is also a pretty easy task.


The specified Git repository has to be accessible by Cycloid's API and potentially by Cycloid workers if you want to use it inside a pipeline.


If you manually add or remove a stack in the git repository of your stack, or if you do any changes in a .cycloid.yml file, a refresh of the stack is required.

To do so:

  1. Go on your catalog-repositories page.
  2. Then hit the Refresh this repository button on your private catalog repositories.

Read more about .cycloid.yml file here.

# Credentials configuration

A private stack is located under a git repository. To access this repository you will first need to add a new SSH credential to access it. You can do it from Cycloid credentials manager.

To do so, go to the Security/Credentials page using the main navigation.


From there you can either select an existing credential or create a new one, but make sure to use the SSH or basic_auth credential type.

Add Git Credential

How to use Github access token

Following the documentation, Github access token (opens new window) can be used as basic_auth credential.

  1. First create a basic_auth credential, set your Github username as username and the Github generated token as password.
  2. Then you will be able to create or update your catalog-repositories and config-repositories with this new basic_auth credential.

Then go to the Catalog repositories in the main navigation menu to start creating a new one using the previously added SSH credential.

Manage Organizations

# Catalog repository configuration

Click on the Add private catalog button to access the catalog repository creation form:

Add Private Catalog Repository button

From here, you'll only need to add four information:

  • A name for your catalog repository
  • The git URL in ssh format of your catalog repository (i.e. git@github.com:demonstration/my-catalog.git)
  • A previously created credential (see Credentials)
  • The branch of your choice which will contain all the stacks


The specified Git repository has to be accessible by Cycloid's API and potentially by Cycloid workers if you want to use it inside a pipeline.

Create a Catalog Repository

To update a catalog repository you can go the catalog repository list page and click on the one you want to edit.

# Tips and tricks

As described in Concept of a stack, during a deployment, the stack and the config are merged. That means you can put whatever you want in the stack or in the config, keeping in mind that the file in config will override the one located in stack. There is no limit, in some specific cases you can even override an entire stack with config if you respect the same files path.

Stack Config

So, all things required in the config are usually defined by the stack. You can create a stack which does not require any config, or you can create a stack which requires a lot of variables, template, files etc. from the config.