Skip to content

Project Setup#

Projects

In order for AWX to pull from a GitHub repository, a deployment key has to be set up.

You will need: - Install and log in to Azure CLI - A public/private key pair (You can create one using sshkeygen, etc.) - Below we have a code snippet that can be used to do this - Access to your Azure Key vault. See how to add your IP address to the allowlist for the firewall here - Source Control URL for your repository (SSH not HTTPS) ex. git@github.umn.edu:oit-EXAMPLE/EXAMPLE.git

Generating a keypair with sshkeygen in BASH#

The following BASH code snippet logs in to Azure, creates variables, runs ssh-keygen with the variables, then pushes the private key to the Azure key vault using the same variables. The saved private key will appear in your key vault with the naming convention nameofrepository-dk (dk meaning deploy key)

Text Only
az login

repo="" # fill in the name of your github repo; this will be used as the name of a Secret in Azure Keyvault. Secret names can only contain alphanumeric characters and dashes, so adjust as needed.
email="" # add your email address
vault="" # name of your Azure Key vault, it should be <unit>-awx .. example devex-awx
# Run command to create public/private key
ssh-keygen -t ed25519 -C $email -f $repo
# Push private key to azure key vault so Tower can access it.
az keyvault secret set -n "$repo-dk" --vault-name $vault --file $repo --subscription e9df6368-79c8-4789-b3ba-75611c2571ba #Devex-common subscription
NOTE: If the az keyvault command gives you the error Client address is not authorized and caller is not a trusted service. Follow these directions to update the firewall.

Store Private Key in Secrets Management#

Keys uploaded through the portal will lose proper formatting. Please use Azure Cli. If you are using Azure Key Vault, add the private key to your vault using the following command if you didn't already run it from the previous code snippet:

az keyvault secret set -n <SECRET NAME> --vault-name "<KEYVAULT NAME>" --file <SECRETFILE NAME>

Create Deploy Key in GitHub for your repository#

  1. Navigate to your repo's deploy key settings
    • In your repo on github: Settings tab >> Deploy Keys >> Add deploy key
    • Use the public key created above or
    • (Github Docs to create key)
  2. Give it a title
  3. Paste the public key into the Key text box
  4. Do not Allow write access; leave this box unchecked
  5. Click the 'Add Key' button
  6. (Optional) Store the public key in your secrets management service for future use

Create Source Control Credential in Tower#

  1. Select 'Credentials' under Resources and click the Add button
  2. Add Name, Description, and Organization
  3. Select 'Source Control' from Credential Type dropdown
  4. Find the SCM Private Key field and click the key button to lookup your private key from your secrets management system by name
    • Select your key vault connection and click next
    • Input the name of your secret. You can test it's working with the test button.
  5. Click Save

Create Project#

  1. Navigate to 'Project' under Resources and click the Add button
  2. Add Name, Description, and Organization
  3. Set Source Control Credential Type to git
  4. Paste the Source Control URL (This needs to be the SSH url. For example: git@github.umn.edu:oit-EXAMPLE/EXAMPLE.git)
  5. Lookup your Source Control Credential using the magnifying glass icon
    • (optional) select a Source Control Branch/Tag/Commit
    • (optional) check any options you'd like
      • Sync on launch is great for not needing to manually sync your project after you make updates to the code in GitHub
  6. Execution Environment (Optional) - This will set the EE for all Templates based on the Project
  7. If you are Leveraging HashiCorp Vault to store secrets that Tower will be using, the environment needs the hvac python module. This is not provided in the default environment, however you can select devex-ee and it will have it
  8. Also, some common roles/collections are included so you don't need to call them out in the requirements.yml file
  9. Note, the Default EE can also be set at the Organization level. Go to the Org Page and click on the pencil icon (edit) next to your Org name and the Default EE can be be set.
  10. Click Save

The source control sync should begin immediately. You can see it from the projects page.or under 'Jobs' as type 'Source Control Update'.