Why use Git and GitHub?
GitHub is a system that provides Git remotes, essentially, an internet accessible backup to the git repositories on your computer. Using a remote enables a pipeline to access and update the state and configuration files.
Git is a commonly used version control tool. It can be used to track code changes made to files in a repository (or "repo"). Changes can then be "pushed" to or "pulled" from remote copies of that repository.
Note There are many alternatives to GitHub including Gitlabs, Google Cloud Source Repositories, and so on. Any remote Git client will work with Platform Automation Toolkit and Concourse. See the Concourse Git resource documentation for details.
To learn more about Git and GitHub, read this short git handbook.
Creating a Git repository
To create a new, local Git repo:
# start a new repository
git init my-platform-automation
# navigate to the new directory it creates
cd my-platform-automation
# create a new directory for your config
mkdir config
# create remaining directories
mkdir env state vars
# create config files for director and opsman
touch config/director.yml
touch config/opsman.yml
# create env file
touch env/env.yml
# create state file
touch state/state.yml
# Optional:
# create vars files for parameters corresponding to configs
touch vars/director-vars.yml
touch vars/opsman-vars.yml
# commit the file to the repository
git commit -m "add initial files"
Creating a GitHub Repository
Go to GitHub and create a new remote repository.
Under your profile, select Repositories.
Select New.
Name your new repository and follow the prompts.
When prompted, do not add any default files.
Copy the URL of your new GitHub repository.
Set the local Git repo's remote to the new GitHub repo:
# enter the path for the new GitHub repo git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git # push your changes to the default branch git push --set-upstream origin main
You should now see your GitHub repo populated with the directories and empty files.
Important A GitHub repository may be referenced as a remote repo by HTTPS or by SSH. In general, SSH keys are more secure. The Concourse Git resource supports using SSH keys to pull from a repository. For more information on using SSH keys with GitHub, see the SSH documentation.
Recommended file structure
You now have both a local Git repo and a remote on GitHub, including the recommended structure for a Platform Automation Toolkit configuration repo:
├── my-platform-automation
│ ├── config
│ ├── env
│ ├── state
│ └── vars
| Folder name | Contents |
|---|---|
| config | Holds config files for the products installed on your foundation. If using CredHub and/or vars files, these config files should contain your ((parametrized)) values. |
| env | Holds env.yml, the environment file used by tasks that interact with Tanzu Operations Manager. |
| vars | Holds product-specific vars files. The fields in these files are used to fill in ((parameters)) during interpolation steps. |
| state | Holds state.yml, which contains the VM ID for the Tanzu Operations Manager VM. |
For further details about the contents of these files, see Inputs and outputs.
Caution Never commit secrets to Git. It is a best practice not to commit secrets, including passwords, keys, and sensitive information, to Git or GitHub. Instead, use ((parameters)). For more information about a recommended way to do this using CredHub or vars files see Using a secrets store to store credentials.
Multi-foundation structure
The setup described in this topic is just one example of how to structure your configuration repository. You may instead decide to have a repo for just config files and separate repos just for vars files. This decouples the config parameter names from their values for multi-foundation templating.
There are many possibilities for structuring Git repos in complex situations. For guidance on how to best set up your git's file structure, see Inputs and outputs. Take note of the inputs and outputs of the various Platform Automation Toolkit tasks. As long as the various input / output mappings correctly correlate to the expected inputs and outputs of the Platform Automation Toolkit tasks, any file structure could theoretically work.
