In today’s software development landscape, Continuous Integration and Continuous Deployment (CI/CD) are crucial for achieving efficiency and reliability. One powerful combination is utilizing GitLab CI to trigger job templates in AWX (Ansible Tower) when changes are merged into the main branch. This guide will walk you through the necessary steps to implement this workflow seamlessly.

Prerequisites

Before diving in, ensure you have the following:

• GitLab Account: A project set up in GitLab.
• AWX Setting: An instance of AWX or Ansible Tower configured and accessible from your GitLab CI environment.
• API Token: An API token from AWX for authentication.
• Job Template: A job template set up within AWX that you want to trigger.

Step 1: Create an API Token in AWX

To allow GitLab CI to trigger the AWX job template, you need an API token:

1. Log into your AWX instance.
2. Navigate to “Settings” → “Tokens” in the left sidebar.
3. Click “Add” to create a new token.
4. Provide a name for the token and select the user (make sure the user has access to the job template).
5. Click “Save” and copy the token. You will need this in your GitLab CI configuration.

Step 2: Store Secrets in GitLab CI/CD Settings

It’s crucial to keep your API token secure. GitLab allows you to store secrets in CI/CD settings, which can be accessed during the pipeline execution:

1. Go to your GitLab project.
2. Navigate to “Settings” → “CI/CD”.
3. Expand the “Variables” section.
4. Click “Add variable”.
   • Key: AWX_API_TOKEN
   • Value: (Paste your AWX API Token)
   • Set it as protected if you want it to be available only in protected branches.
   • Set it as masked to hide the token in job logs.
5. Repeat the process to add any other necessary configurations like AWX_URL and JOB_TEMPLATE_ID.

Step 3: Create GitLab CI Configuration File

You will need to create or edit the .gitlab-ci.yml file in your GitLab repository to define the CI/CD pipeline. Below is a sample configuration that demonstrates how to execute an AWX job template when a merge to the main branch occurs.

stages:
  - trigger_awx

trigger_awx_job:
  stage: trigger_awx
  image: curlimages/curl:latest
  script:
    - 'curl -X POST -H "Authorization: Bearer $AWX_API_TOKEN" -H "Content-Type: application/json" -d "{\"extra_vars\": {<fill if you want or remove if not>}}" "$AWX_URL/api/v2/job_templates/$JOB_TEMPLATE_ID/launch/"'
  only:
    refs:
      - main

Explanation of the Configuration

• stages: Defines the stages of your pipeline. Here, we have one stage called trigger_awx.
• trigger_awx_job: A job that triggers the AWX job template.
• script: The command executed by the runner. This uses curl to send a POST request to the AWX API endpoint to launch the job template. Make sure to replace README.md in the changes section with your actual files of interest.
• only: Restricts the job execution to only when changes have been merged into the main branch.

Step 4: Test Your Configuration

Once you’ve set everything up, it’s time to test:

1. Make a change in a branch other than main.
2. Merge that change into the main branch using a Merge Request.
3. Check the Pipeline tab in your GitLab project to see if the job runs successfully.
4. Monitor your AWX dashboard to ensure the job template was triggered correctly.

Conclusion

By configuring GitLab CI to trigger an AWX job template upon merging changes to the main branch, you streamline your CI/CD process while maintaining flexibility and control over your automation. This integration not only boosts efficiency but also ensures that your deployment processes remain robust and repeatable.

Happy coding, and may your pipelines flow smoothly!

Further Resources

• GitLab CI/CD Documentation
• AWX API Documentation