Skip to content

Ansible Collection

This CI/CD template contains all of the CI jobs required for a pipeline for an Ansible Collection Project.

Requirements

The following requirements are needed to run these CI/CD jobs. As we use commitizen for the versioning system, your commits will be required to be in conventional commit format. The configuration for commitizen is within a .cz.yaml file which you will need to add to your repository root directory.

Gitlab Features

Feature Setting Notes
Package Registry On Storage of pipeline artifacts and the built package.
Releases On Gitlab releases are created as part of the pipeline.

Variables

To be able to upload to Ansible Galaxy, you will be required to provide the jobs, the following Variables That should be set as CI/CD variables (<Project> -> Settings -> CI/CD Settings -> Variables).

Variable Settings Notes
ANSIBLE_GALAXY_UPLOAD_TOKEN masked, protected
VERSION_BUMP_INCREMENT major, minor, patch Used for manual run of the job. After setting the variable, that type of version bump will occur.

Within your .gitlab-ci.yml file there are varibales to be set, please see below.

.gitlab-ci.yaml Changes

To include these jobs in your CI/CD Project add our gitlab-ci project as a submodule to your project git submodule add https://gitlab.com/nofusscomputing/projects/gitlab-ci/. Then update your projects .gitlab-ci.yml file to include the following:

variables:
  ANSIBLE_GALAXY_SERVER_URL: https://galaxy.ansible.com    # Optional, default=(as displayed)String. URL to the Galaxy server for uploads
  ANSIBLE_GALAXY_NAMESPACE: ""                             # Mandatory, String. The ansible galaxy upload namespace
  ANSIBLE_GALAXY_PACKAGE_NAME: ""                          # Mandatory, String. The Ansible Galaxy package name

include:
  - project: nofusscomputing/projects/gitlab-ci
    ref: <git ref>    # branch, git tag, commit etc
    file:
      - .gitlab-ci_common.yaml
      - template/ansible-collection.gitlab-ci.yaml

CI/CD Jobs

This template contains the following CI/CD Jobs

  • Create Release

  • Ansible Lint

  • Ansible Lint (galaxy.yml)

  • Build Collection

  • Stage Collection

  • Gitlab Release

  • Ansible Galaxy

for a detail description of each job, please see below.

Create Release

Triggered:

  • Feature branch:

    • push: never

    • merge to: never

  • development branch:

    • push: manual

    • merge to: manual

  • master branch:

    • push: always

    • merge to: always

  • git tag: never

Create a release. It's only triggered on merge to the development and master branches. The last stage of this job is to create a git tag which matches the version to be released. The creation of the git tag, starts the remainder of the release cycle. On the development branch (when the job is triggered as it's a manual job) an alpha release is created and on the master branch, a full release is created.

Ansible Lint

Triggered:

  • Feature branch:

    • push: never

    • merge to: never

  • development branch:

    • push: manual

    • merge to: manual

  • master branch:

    • push: never

    • merge to: never

  • git tag: never

Lints the yaml files in directories meta, playbooks and roles. This job will not fail the pipeline. There are XUnit test reports created for thyis job so you can see any liniting errors.

Ansible Lint (galaxy.yml)

Triggered:

  • Feature branch:

    • push: always

    • merge to: always

  • development branch:

    • push: always

    • merge to: always

  • master branch:

    • push: never

    • merge to: never

  • git tag: always

Lints the galaxy.yml file. This job is designed to fail the pipeline, as an incorrectly formated galaxy.yml file can prevent an upload of the collection to Ansible Galaxy. There is a XUnit test report created for thyis job so you can see any liniting errors.

Build Collection

Triggered:

  • Feature branch:

    • push: always

    • merge to: always

  • development branch:

    • push: always

    • merge to: always

  • master branch:

    • push: never

    • merge to: never

  • git tag: always

Builds the collection.

Stage Collection

Triggered:

  • Feature branch:

    • push: never

    • merge to: never

  • development branch:

    • push: never

    • merge to: never

  • master branch:

    • push: never

    • merge to: never

  • git tag: always

Adds the collection to Gitlab Packages Regsitry as a generic package. This location is used to store the package.

Gitlab Release

Triggered:

  • Feature branch:

    • push: never

    • merge to: never

  • development branch:

    • push: never

    • merge to: never

  • master branch:

    • push: never

    • merge to: never

  • git tag: always

Creates a Gitlab release.

Ansible Galaxy

Triggered:

  • Feature branch:

    • push: never

    • merge to: never

  • development branch:

    • push: never

    • merge to: never

  • master branch:

    • push: never

    • merge to: never

  • git tag: always

Uploads the package to Ansible Galaxy.

CI Tests

Still to be developed

Definition

template/ansible-collection.gitlab-ci.yaml
  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
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
include:
  - local: $JOB_ROOT_DIR/ansible/collection/.gitlab-ci.yml
  - local: $JOB_ROOT_DIR/lint/ansible.gitlab-ci.yaml


Create Release:
  extends: .ansible_collection_merge
  needs: []


Ansible Lint:
  extends: .ansible_linter_defaults
  image: python:3.11-slim
  variables:
    ANSIBLE_LINT_PATH: meta/ playbooks/ roles/
  needs: []
  rules:

    - if: $CI_COMMIT_TAG
      when: always

    - if: "$CI_COMMIT_AUTHOR =='nfc_bot <helpdesk@nofusscomputing.com>'"
      when: never

    - if: # Occur on merge
        $CI_COMMIT_BRANCH == "development"
          &&
        $CI_PIPELINE_SOURCE == "push"
      when: always

    - if:
        $CI_COMMIT_BRANCH != "development"
          &&
        $CI_COMMIT_BRANCH != "master"
          &&
        $CI_PIPELINE_SOURCE == "push"
      when: always

    - when: never


# ToDo: add lint for README.md as ansible Galaxy doesn't seem to like html in the md document. 16 Feb 24.


Ansible Lint (galaxy.yml):
  extends: .ansible_linter_defaults
  image: python:3.11-slim
  variables:
    ANSIBLE_LINT_PATH: galaxy.yml
    TEST_MUST_PASS: 'yes'
  needs: []
  rules:

    - if: $CI_COMMIT_TAG
      when: always

    - if: "$CI_COMMIT_AUTHOR =='nfc_bot <helpdesk@nofusscomputing.com>'"
      when: never

    - if: # Occur on merge
        $CI_COMMIT_BRANCH == "development"
          &&
        $CI_PIPELINE_SOURCE == "push"
      when: always

    - if:
        $CI_COMMIT_BRANCH != "development"
          &&
        $CI_COMMIT_BRANCH != "master"
          &&
        $CI_PIPELINE_SOURCE == "push"
      when: always

    - when: never


Build Collection:
  extends: .ansible_collection_build
  needs:
    - Ansible Lint
    - Ansible Lint (galaxy.yml)


Stage Collection:
  extends: .ansible_collection_stage_package
  needs:
    - Build Collection


Gitlab Release:
  extends: .ansible_collection_release
  needs:
    - Stage Collection


Ansible Galaxy:
  extends: .ansible_collection_publish_galaxy
  needs:
    - Stage Collection
    - Gitlab Release
.gitlab-ci_common.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
variables:
    JOB_ROOT_DIR: 'gitlab-ci'
    GIT_SUBMODULE_STRATEGY: normal
    #PIPELINE_RUN_TRIGGER: 'false'
    PIPELINE_RUN_SCHEDULE: 'true'

stages:
    - chores
    - validation
    - build
    - prepare
    - test
    - release
    - sync
    - deploy
    - publish

About:

This page forms part of our Project Gitlab-CI.

Page Metadata
Version: ToDo: place files short git commit here
Date Created: 2024-02-16
Date Edited: 2025-12-03

Contribution:

Would You like to contribute to our Gitlab-CI project? You can assist in the following ways:

 

ToDo: Add the page list of contributors