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 will enable 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 within a repository (or "repo"). Changes can then be "pushed" to or "pulled" from remote copies of that repository.

GitHub alternatives

There are many alternatives to GitHub including Gitlabs, Google Cloud Source Repositories, etc. Any remote Git client will work with Platform Automation Toolkit and Concourse. Refer to the Concourse Git resource documentation for details.

To learn more about Git and Github, you can 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

Next, navigate to GitHub and create a new remote repository.

Under your profile, select "Repositories"
Select "New"
Name your new repository and follow the prompts
Do not select to add any default files when prompted
Copy the URL of your new GitHub repository

Now, we can 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.

Using GitHub with SSH

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, refer to this SSH documentation.

Recommended File Structure

You now have both a local Git repo and a remote on GitHub. The above commands give you the recommended structure for a Platform Automation Toolkit configuration repo:

├── my-platform-automation
│   ├── config
│   ├── env
│   ├── state
│   └── vars

config	Holds config files for the products installed on your foundation. If using Credhub and/or vars files, these config files should have your `((parametrized))` values present in them
env	Holds `env.yml`, the environment file used by tasks that interact with Ops Manager.
vars	Holds product-specific vars files. The fields in these files get used to fill in `((parameters))` during interpolation steps.
state	Holds `state.yml`, which contains the VM ID for the Ops Manager VM.

For further details regarding the contents of these files, please refer to the Inputs and Outputs documentation.

Never commit secrets to Git

It is a best practice to not commit secrets, including passwords, keys, and sensitive information, to Git or GitHub. Instead, use ((parameters)). For more information on a recommended way to do this, using Credhub or vars files, review the handling secrets documentation.

Multi-foundation

The above 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 these complex situations. For guidance on how to best set up your git's file structure, refer to the Inputs and Outputs documentation and 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 ins and outs of the Platform Automation Toolkit tasks, any file structure could theoretically work.

1	`[activate-certificate-authority]: ../tasks.md#activate-certificate-authority`