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
yml suffix (e.g.
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.
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.
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.
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
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.
Note: When the repository is not public, the
passwordproperties 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
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.
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
DONEstate 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 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.
synchronizeSource control tasks have predefined
onFailurePolicy switches that are set to
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 occurs immediately when a Source CI is saved, or periodically if a property for Stitch Source periodic synchronisation is enabled and configured.
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.