Manage blueprint repositories

A blueprint repository is a remote repository that contains templates and source code for blueprint functionality. Each time you run the XL CLI xl blueprint command, it fetches files from the blueprint repository.

Repository types

You can define one or more of the following blueprint repository types:

Local server
HTTP
GitHub online repository
Bitbucket Cloud
Bitbucket Server (on-premise)
GitLab (Cloud and on-premise)

Define blueprint repositories

Defined blueprint repositories are stored in the ~/.xebialabs/config.yaml file. This file is created automatically when you run any XL CLI command after installing the XL CLI. When you run the xl blueprint command, this file’s presence on your system enables you to select one of the available blueprints stored in a repository.

On initial installation, the config.yaml file is configured to access the Deploy/Release public blueprint repository provided in the Deploy/Release public software distribution site.
You can also configure your own HTTP blueprint repository and update the config.yaml file to point to it.
You can define multiple blueprint repositories in your config.yaml file.

HTTP repository configuration fields

Here are the configuration fields for an HTTP repository in the config.yaml file:

Field	Expected value	Default value	Required	Description
`name`	—	—	Yes	Repository configuration name
`type`	`http`	—	Yes	Repository type
`url`	—	—	Yes	HTTP repository URL, including protocol
`username`	—		No	Basic authentication username
`password`	—		No	Basic authentication password

Note: Only basic authentication is supported at the moment for remote HTTP repositories.

Local repository configuration

The type: local repository is mainly intended to be used for local development and tests. Any local path can be used as a blueprint repository with this type.

Field	Expected value	Default value	Required	Description
`name`	-	-	Yes	Repository configuration name
`type`	`local`	-	Yes	Repository type
`path`	-	-	Yes	Full local path where blueprint definitions can be stored. `~` can be used for stating the current user’s home directory under Unix systems.
`ignored-dirs`	-	-	No	List of comma-separated directories, to be ignored while traversing the local path. Example: `.git`, `some-other-dir`
`ignored-files`	-	-	No	List of comma-separated files, to be ignored while traversing the local path. Example: `.DS_Store`, `.gitignore`

Notes

In the case of local repositories, if the path is set too generically - such as ~ - the traversal path will be big and may result in the blueprint command running very slowly.
in development you can use the -l flag to use a local repository directly without defining it in configuration. For example, to execute a blueprint in a local directory ~/mySpace/myBlueprint you can run xl blueprint -l ~/mySpace -b myBlueprint.

Define multiple repositories

You can specify multiple blueprint repositories in your config.yaml file.

Important notes:

Only one of the listed repositories will be active at a given time.
The active blueprint repository should be stated using the current-repository field in the configuration file.
If the defined blueprint repository cannot be reached, an error displays.
If the current-repository field is not stated, an error displays.

Here is the format for the blueprint section of the config.yaml file that points to a GitHub repository, the public XebiaLabs HTTP repository, a local repository that you create, and Bitbucket Cloud, Bitbucket Server, and GitLab repositories:

    blueprint:
      current-repository: XL Blueprints
      repositories:
        - name: xebialabs-github
          type: github
          repo-name: blueprints
          owner: xebialabs
          token: my-github-token
          branch: master
        - name: xebialabs-dist
          type: http
          url: http://dist.xebialabs.com/public/blueprints
        - name: test
          type: local
          path: /path/to/local/test/blueprints/
          ignored-dirs: .git, .vscode
          ignored-files: .DS_Store, .gitignore
        - name: Bitbucket Cloud
          type: bitbucket
          owner: xebialabs
          repo-name: blueprints
          branch: master
          token: bitbucket-token
        - name: Bitbucket server
          type: bitbucketserver
          user: xebialabs
          url: http://localhost:7990
          project-key: XEB
          repo-name: blueprints
          branch: master
          token: bitbucket-token
        - name: Gitlab
          type: gitlab
          owner: xebialabs
          url: http://localhost
          repo-name: blueprints
          branch: master
          token: gitlab-token
      xl-deploy:
        authmethod: basic
        password: admin
        url: http://localhost:4516
        username: admin
      xl-release:
        authmethod: basic
        password: admin
        url: http://localhost:5516
        username: admin

Note that the xebialabs-github repository is declared as the default in this example.

GitHub repository configuration fields

You can maintain blueprints in one or more GitHub repositories and specify these details in your config.yaml file.

Here are the configuration fields for a GitHub repository in the config.yaml file:

Field	Expected value	Default value	Required?	Details
`name`	—	—	Yes	Repository configuration name
`type`	`github`	—	Yes	Repository type
`repo-name`	—	—	Yes	GitHub remote repository name
`owner`	—	—	Yes	GitHub remote repository owner Can be different than the user accessing it
`branch`	—	`master`	No	GitHub remote repository branch to use
`token`	—		No	GitHub user token, please refer to GitHub documentation for generating one. Repo read permission is required when generating the token for the XL CLI

Note: When the token field is not specified, the GitHub API will be accessed in unauthenticated mode and the rate limit will be much less than the authenticated mode. According to the GitHub API documentation, the unauthenticated rate limit per hour and per IP address is 60, whereas the authenticated rate limit per hour and per user is 5000. You should set the token field in your configuration so as not to receive any GitHub API related rate limit errors.

Define a single GitHub repository

Here is an example of the blueprint section of a config.yaml file that is configured to access a GitHub repository:

blueprint:
  current-repository: my-github
  repositories:
  - name: my-github
    type: github
    repo-name: blueprints
    owner: mycompany
    branch: master
    token: my-github-token

Define multiple GitHub and HTTP repositories

You can specify multiple GitHub and/or HTTP blueprint repositories in your config.yaml file.

Important notes:

Only one of the listed repositories will be active at a given time.
The active blueprint repository should be stated using the current-repository field in the configuration file.
If the defined blueprint repository, or current-repository field is not stated, the XL CLI will auto-update the config.yaml file with the default Deploy/Release Blueprint repository.

Here is the format for the blueprint section of the config.yaml file that points to the public XebiaLabs HTTP repository and a second GitHub repository you create:

blueprint:
  current-repository: my-github
  repositories:
  - name: xl-dist
    type: http
    url: https://dist.xebialabs.com/public/blueprints/
  - name: my-github
    type: github
    repo-name: blueprints
    owner: mycompany
    branch: master
    token: GITHUB_TOKEN

Manually specify a blueprint using the `blueprint` command

You can choose to explicitly specify a local or remote folder path to a blueprint when running the blueprint command. Supported options depend on the version of the DevOps Platform software and XL CLI you are running. See the xl blueprint command in the XL CLI command reference for details.

Repository structure example

To better understand the file and folder structure of a blueprint repository, review the public Deploy/Release Blueprint repository.

For example, you can drill down from the root of this repository to see how the Microservice Application on Amazon EKS blueprint is structured:

blueprints
├── index.json
└── aws/
      └── microservice-ecommerce/
            ├── blueprint.yaml
            ├── xebialabs.yaml
            ├── cloudformation/
            │     ├── template1.yaml.tmpl
            │     └── template2.yaml
            │
            └── xebialabs/
                  ├── xld-environment.yaml.tmpl
                  ├── xld-infrastructure.yaml.tmpl
                  ├── xlr-pipeline.yaml.tmpl
                  └── README.md.tmpl

The repository structure consists of:

index.json file: The index.json file at the root level of an HTTP blueprint repository provides an index listing off the blueprints stored in the repository, enabling you to select one of these blueprints using the XL CLI.

For example, the index.json file in the Deploy/Release public repository defines the available blueprints:
```
[
"aws/monolith",
"aws/microservice-ecommerce",
"aws/datalake",
"docker/simple-demo-app"
]
```
Notes:
- The index.json file is not needed for a GitHub type repository.
- If you choose to set up a new HTTP repository, you must update the JSON file to reflect your new repository.
- To automatically generate an index.json file on your release pipeline, you can refer to the sample generate_index.py python script in the official Deploy/Release Blueprint GitHub repository.
Blueprint template files: All files with tmpl extension are templates for the blueprint. These template files will be passed through generator to create “ready-to-use” YAML files.
Regular files and folders: All files and directories will be copied directly.

File details

Here are the file details for the Microservice Application on Amazon EKS blueprint example.

microservice-ecommerce/
            ├── blueprint.yaml
            ├── xebialabs.yaml
            ├── cloudformation/
            │     ├── template1.yaml.tmpl
            │     └── template2.yaml
            │
            └── xebialabs/
                  ├── xld-environment.yaml.tmpl
                  ├── xld-infrastructure.yaml.tmpl
                  ├── xlr-pipeline.yaml.tmpl
                  └── README.md.tmpl

blueprint.yaml file: Each application must have a blueprint.yaml in which you specify the required user prompts and files used for the blueprint.
- See the Blueprint YAML format for a description of this file structure.
- For a working example, open the XebiaLabs Microservices e-commerce blueprint.yaml file to review the metadata, parameters, variables and files defined for this blueprint.
xebialabs.yaml file: This file is an entry point for xl apply command. For your convenience, this file combines all Deploy and Release YAML templates as an Import kind, enabling you to apply a blueprint with a single command.
cloudformation folder: This folder is specific to AWS, containing CloudFormation templates used to provision the AWS infrastructure from Deploy. Other blueprint types will include folders and files specific to the type of application.
xebialabs folder: You place your Deploy/Release YAML templates in this folder. This folder will also include any generated files, including .gitignore, values.xlvals and secrets.xlvals files.