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.
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
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:
1 2 3 4 5
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:
1 2 3 4 5
Holds config files for the products installed on your foundation.
If using Credhub and/or vars files,
these config files should have your
Holds product-specific vars files.
The fields in these files get used to fill in
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
For more information on a recommended way to do this,
using Credhub or vars files,
review the handling secrets documentation.
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
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.