cloud-foundation-fabric/fast/extras/0-cicd-github/README.md

FAST GitHub repository management

This small extra stage allows creating and populating GitHub repositories used to host FAST stage code, including rewriting of module sources and secrets used for private modules repository access.

It is designed for use in a GitHub organization, and is only meant as a one-shot solution with perishable state especially when used for initial population, as you don't want Terraform to keep overwriting your changes with initial versions of files.

Initial population is only meant to be used with actual stage, while populating the modules repository should be done by hand to avoid hitting the GitHub hourly limit for their API.

Once initial population is done, you need to manually push to the repository

• the .tfvars file with custom variable values for your stages
• the workflow configuration file generated by FAST stages

GitHub provider credentials

A GitHub token is needed to authenticate against their API. The token needs organization-level permissions, like shown in this screenshot:

Once a token is available set it in the GITHUB_TOKEN environment variable before running Terraform.

Variable configuration

The organization required variable sets the GitHub organization where repositories will be created, and is used to configure the Terraform provider.

Modules repository and sources

The modules_config variable controls creation and management of the key and secret used to access the private modules repository, and indirectly control population of initial files: if the modules_config variable is not specified no module repository is know to the code, so module source paths cannot be replaced, and initial population of files cannot happen. If the variable is specified, an optional source_ref attribute can be set to the reference used to pin modules versions.

This is an example that configures the modules repository name and an optional reference, enabling initial population of repositories where the feature has been turned on:

modules_config = {
  repository_name = "GoogleCloudPlatform/cloud-foundation-fabric"
  source_ref      = "v19.0.0"
}
# tftest skip

In the above example, no key options are set so it's assumed modules will be fetched from a public repository. If modules repository authentication is needed the key_config attribute also needs to be set.

If no keypair path is specified an internally generated key will be stored as an access key in the modules repository, and as secrets in the stage repositories:

modules_config = {
  repository_name = "GoogleCloudPlatform/cloud-foundation-fabric"
  key_config = {
    create_key     = true
    create_secrets = true
  }
}
# tftest skip

To use an existing keypair pass the path to the private key, the public key name is assumed to have the same name ending with the .pub suffix. This is useful in cases where the access key has already been set in the modules repository, and new repositories need to be created and their corresponding secret set:

modules_config = {
  repository_name = "GoogleCloudPlatform/cloud-foundation-fabric"
  key_config = {
    create_secrets = true
    keypair_path   = "~/modules-repository-key"
  }
}
# tftest skip

Repositories

The repositories variable is where you configure which repositories to create and whether initial population of files is desired.

This is an example that creates repositories for stages 00 and 01, and populates initial files for stages 00, 01, and 02:

repositories = {
  fast_00_bootstrap = {
    create_options = {
      description = "FAST bootstrap."
      features = {
        issues = true
      }
    }
    populate_from = "../../stages/0-bootstrap"
  }
  fast_01_resman = {
    create_options = {
      description = "FAST resource management."
      features = {
        issues = true
      }
    }
    populate_from = "../../stages/1-resman"
  }
  fast_02_networking = {
    populate_from = "../../stages/2-networking-peering"
  }
}
# tftest skip

The create_options repository attribute controls creation: if the attribute is not present, the repository is assumed to be already existing.

Initial population depends on a modules repository being configured in the modules_config variable described in the preceding section and on thepopulate_from attributes in each repository where population is required, which point to the folder holding the files to be committed.

Commit configuration

Finally, a commit_config variable is optional: it can be used to configure author, email and message used in commits for initial population of files, its defaults are probably fine for most use cases.

Files

name	description	resources
cicd-versions.tf	Provider version.
main.tf	Module-level locals and resources.	github_actions_secret · github_repository · github_repository_deploy_key · github_repository_file · tls_private_key
outputs.tf	Module outputs.
providers.tf	Provider configuration.
variables.tf	Module variables.

Variables

name	description	type	required	default
organization	GitHub organization.	string	✓
commmit_config	Configure commit metadata.	object({…})		{}
modules_config	Configure access to repository module via key, and replacement for modules sources in stage repositories.	object({…})		null
repositories	Repositories to create.	map(object({…}))		{}

Outputs

name	description	sensitive
clone	Clone repository commands.