AWX in Action

Triggering Workflows From CI: A GitHub Actions Example

Triggering a job template from external systems, like CI services, is useful in many cases. For example:

• You can trigger a job template to deploy a new version of your application after a successful build.
• You can automatically deploy a new environment for each new feature branch.
• You can automate testing environments creation and deletion when a new pull request is opened or closed.
• Etc.

In this example, we'll demonstrate how to call a job template from a CI system. We'll use GitHub Actions to trigger the DeployAndCheckPostgreSQL workflow. The same kind of integration can be done with GitLab CI/CD and any other CI system with a few modifications. By understanding how to trigger a job template from GitHub Actions, you can adapt the same process to your favorite CI system.

Let's proceed.

First, we'll use the GH CLI to create a repository. If you prefer creating the repository manually without using the GH CLI, you can do that too.

Start by installing the GH CLI and Git if you haven't already:

# Install git 
dnf install -y git

# Install config manager
dnf install 'dnf-command(config-manager)'

# Add the GH CLI repository
dnf config-manager \
  --add-repo https://cli.github.com/packages/rpm/gh-cli.repo

# Install the GH CLI
dnf install gh --repo gh-cli -y

We need to authenticate the CLI with GitHub. You can either use the token we created earlier or create a new one. If you want to create a new one, go to your GitHub account and generate a new token. Make sure to select the repo and admin:public_key scopes to activate the necessary permissions. Then execute the following commands and make sure to replace , , and with your GitHub token, username, and email address respectively:

# Authenticate with GitHub by exporting the token
export GH_TOKEN=

# Export the GitHub username
export GH_USER=

# Export the GitHub email
export GH_EMAIL=

Let's create a new repository called demo-awx-api:

gh repo create demo-awx-api --private

Create a new directory for the GitHub repository:

mkdir -p $HOME/demo-awx-api/.github/workflows
cd $HOME/demo-awx-api

Initialize a new Git repository:

git init

Add an author identity:

git config --global user.email "$GH_EMAIL"
git config --global user.name "$GH_USER"

Change the branch name to main:

git branch -M main

Add the remote repository:

git remote add origin git@github.com:$GH_USER/demo-awx-api.git

Add your SSH key to GitHub:

gh ssh-key add ~/.ssh/id_rsa.pub --title "AWX"

Create a file called README.md with the following command:

cat < README.md
# Demo AWX api
This is a demo repository to show how to trigger an AWX job template using the api.
EOF

Add the README.md file to the staging area:

git add README.md

Commit the changes:

git commit -m "Initial commit"

Push the changes to the remote repository:

git push -u origin main

We'll also create a new user in AWX that we'll call GitHubActionsUser. This user will be used to authenticate GitHub Actions with AWX. Go to Users in the AWX web interface and create a new user with the following configurations:

• Username: Use GitHubActionsUser
• Email: Use any email address you want or leave it empty.
• Password: Use any password you want, for example, GitHubActionsUser.
• Confirm Password: Use the same password as above.
• User Type: Use Normal User.
• Organization: Use AllOrganization.

After creating the user, go to the Roles tab and assign the Execute permission on the DeployAndCheckPostgreSQL workflow to the user. We want the user to be able to run the workflow, and initially, those permissions are enough. However, to see the output of each step in the workflow, we also need to assign the Execute permission on the DeployPostgreSQL and CheckPostgreSQL job templates.

We need to authenticate GitHub Actions with AWX using the GitHubActionsUser user. For security reasons, we won't use the user's password directly in the GitHub Actions workflow. Instead, we'll create a new secret in the GitHub repository to store the password:

export AWX_PASSWORD=
echo $AWX_PASSWORD | gh secret set AWX_PASSWORD

Make sure to replace with the password of the GitHubActionsUser user.

We'll also store the password of the database user in a secret. This is optional, but it's good practice to store sensitive information as secrets. Run the following command to create a new secret in the GitHub repository after replacing with the password you want to use:

export DATABASE_PASSWORD=
echo "$DATABASE_PASSWORD" | gh secret set DATABASE_PASSWORD

Create the GitHub Actions workflow to trigger the job template. Run the following commands after replacing , , and with the public IP address of the AWX server, the URL of the AWX server, and the ID of the DeployAndCheckPostgreSQL workflow job template respectively:

# Export the AWX1_PUBLIC_IP variable
export AWX1_PUBLIC_IP=

# Export the AWX_URL variable
export AWX_URL=https://awx.example.com

# Export the hostname of the AWX server
export AWX_HOSTNAME=awx.example.com

# Export the WORKFLOW_ID variable
export WORKFLOW_ID=

You can obtain the ID of the DeployAndCheckPostgreSQL workflow job template by navigating to the Workflow Job Templates section in the AWX web interface and clicking on the workflow. The ID is the number at the end of the URL (e.g., https://awx.example.com/#/templates/workflow_job_template/23/ => 23).

Finally, we need to create a new GitHub Actions workflow to trigger the job template. If you're not familiar with GitHub Actions, you can read the official documentation to get started. Our goal here is not to learn GitHub Actions, but to demonstrate how to trigger an AWX job template from this tool. Therefore, we'll use a simple yet complete example to achieve our goal.

Let's name the workflow file trigger-awx-job.yml. Execute the following command to create it: