Stitch repositories

A Stitch repository is a source of rules and macros YAML files, and their associated content. A repository can be any Git repository or a local folder that contains a valid Stitch YAML file. When a Stitch source is added to the configuration, Deploy scans the whole repository or the folder structure recursively, drilling down the folder structure attempting to find valid definitions of Stitch YAML rules. It will look for files with the stitch-rules prefix, and a yaml or yml suffix (e.g. stitch-rules.yaml or stitch-rules-k8s-labels.yaml).

Note For optimal performance we strongly recommend that you use a dedicated repository for Stitch files. Storing a large amount of non-Stitch related files inside of the repository may slow down the Stitch synchronisation process.

Stitch files

A Stitch repository can have multiple Stitch YAML files defining different rules or macros. See Stitch rules and Stitch Macros for more information on how they work. Each Stitch YAML file supports multiple documents and the documents in one YAML file can be both Stitch rules or Stitch macros.

Additionally, rules or macros can use external template files. These template files should be defined and placed with relative paths inside of the repository.

Example of an external template definition is as follows:

kind: Rules
metadata:
  namespace: k8s-add-labels
spec:
  - name: "k8s.AddLastLabel"
    condition:
      deployedType: k8s.Resources
    processor:
      - type: freemarker
        description: "Adding last label to kubernetes spec"
        parameters:
          templateFile: templates/label-template.ftl

This example above specifies a relative path to an external template defined in the spec/0/processor/0/parameters/templateFile field. This way the relative templates subdirectory to given Stitch YAML file will be scanned for the label-template.ftl file which should contain a template. Macros can also be defined using external template files, for example:

kind: Macros
metadata:
  namespace: k8s-add-labels
spec:
  - name: "k8s.MacroAddLabels"
    description: This is a macro for adding labels
    parameters:
      application: default-application-name
      const: default-value
    processor:
      - type: freemarker
        description: "Adding app and env label"
        parameters:
          templateFile: templates/label-macro.ftl

The Stitch engine will search for a YAML file as shown in the example above, in a repository file structure. Once the file is found, it will lead to the creation of the k8s.MacroAddLabels macros inside the k8s-add-labels namespace. This will also trigger a scan of the subdirectory templates for the label-marcro.ftl FreeMarker template file.

Source types

Stitch repositories are defined using the Stitch Source CI. Currently, Git or Folder Sources are supported. Definition of the Stitch Source CI can be done using the Stitch Workbench, or by using the CI Explorer by adding it to a Configuration folder. See [Workbench][/deploy/stitch/stitch-workbench ] for more information.

Git sources

A Git source is used to define a repository based on git (e.g. GitHub, private Git repository, etc). The content of such a repository is maintained using external development tools, and the repository’s own access controls.

A Git repository connection is defined either by an SSH or HTTPS connection string in the repositoryUrl CI property. The content of the repository is synchronized by masterBranchName (which allows you to define if for example your main branch is master or main). Additionally, if Stitch workbench is used for GitOps activities on the git repository (adding, editing or publishing of rules) you can define branchRegex which will be used for filtering branches to match those that are related to Stitch changes.

If you want to use an HTTPS connection string, you must specify a value in the repositoryUrl field, e.g. https://github.com/xebialabs/stitch-example-templates.

note

When the repository is not public, the username and password properties should be used as Git connection credentials properties.

When using an SSH connection URL, you must either use a full SSH url with a username ssh://user@host[:port]/repo-name.gitand fill it in the repositoryUrl field; or use the username field and fill in the repositoryUrl with an appropriate value, e.g. ssh://host[:port]/repo-name.git. As for the authentication, you can use either the credentials or a private key by filling in the privateKey field and if needed a private key password phrase in the passphrase field.

Folder sources

A Folder source is used to define a folder on a file system inside the Deploy server. Defining a full path (or a relative to the Deploy server's root folder) inside of the Folder Stitch Source CI would scan the folder for Stitch YAML files.

Source synchronisation

Stitch repositories are automatically scanned everytime a Stitch Source CI is saved (created or modified), or when it is triggered manually from the Workbench or the CI Explorer by running the synchronisation control task.

Synchronisation for a single source is sequential, which means that only one sync job can be run for the same source in the whole cluster.

note

If two sync jobs are run simultaneously in a cluster the one that is run second will end up being in a DONE state with an appropriate message in synchronisation step saying:

Skipping synchronizing Stitch source [source_name] - another sync is already in progress for this source.

Manual Synchronisation

Manual synchronisation can be done by triggering Sync Now from the sources list for a single source or by using the Sync All button on Sources page. Additionally, every source can be synchronised by running the synchronizeSource control task for source CI.

All manual synchronisations are actually Deploy control tasks. See control tasksfor more information.

Source synchronizeSource control tasks have predefined onSuccessPolicy and onFailurePolicy switches that are set to ARCHIVE and CANCEL_AND_ARCHIVE respectively. You can switch off these policies by setting the above properties to NOOP. These policies enable synchronisation tasks to be automatically archived in case they are successful or if they fail.

Automatic Synchronisation

Automatic synchronisation occurs immediately when a Source CI is saved, or periodically if a property for Stitch Source periodic synchronisation is enabled and configured.

Branches Synchronisation

Git Source can have Branches, which are Stitch representation of Git branch. On a Git Source you can define a branchCronExpression which will the automatically do a sync of all Stitch branches on that source and create Branches from them. Additionally, you can also trigger sync of specific Branch on Branches page. On the same page you can also view the logs for the last branches syncs.