|
| 1 | +import CustomizableValue from '/src/components/CustomizableValue'; |
| 2 | + |
| 3 | +# Adding Pipelines to a GitLab Project |
| 4 | + |
| 5 | +This guide walks you through the process of adding Gruntwork Pipelines to a GitLab project. By the end, you'll have a fully configured GitLab CI/CD pipeline that can deploy infrastructure changes automatically. |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +Before you begin, make sure you have: |
| 10 | + |
| 11 | +- Basic familiarity with Git, GitLab, and infrastructure as code concepts |
| 12 | +- Access to one (or many) AWS account(s) where you have permission to create IAM roles and OIDC providers |
| 13 | +- Completed the [Pipelines Auth setup for GitLab](/2.0/docs/pipelines/installation/viamachineusers#gitlab) and setup a machine user with appropriate PAT tokens |
| 14 | +- Local access to Gruntwork's GitHub repositories, specifically [boilerplate](https://github.com/gruntwork-io/boilerplate) and the [architecture catalog](https://github.com/gruntwork-io/terraform-aws-architecture-catalog/) |
| 15 | + |
| 16 | +## Setup Process Overview |
| 17 | + |
| 18 | +Setting up Gruntwork Pipelines for GitLab involves these main steps: |
| 19 | + |
| 20 | +(prerequisite) Complete the [Pipelines Auth setup for GitLab](/2.0/docs/pipelines/installation/viamachineusers#gitlab) |
| 21 | + |
| 22 | +1. [Authorize Your GitLab Group with Gruntwork](#step-1-authorize-your-gitlab-group-with-gruntwork) |
| 23 | +2. [Install required tools (mise, boilerplate)](#step-2-install-required-tools) |
| 24 | +3. [Install Gruntwork Pipelines in Your Repository](#step-3-install-gruntwork-pipelines-in-your-repository) |
| 25 | +4. [Install AWS OIDC Provider and IAM Roles for Pipelines](#step-4-install-aws-oidc-provider-and-iam-roles-for-pipelines) |
| 26 | +5. [Complete the setup](#step-5-complete-the-setup) |
| 27 | + |
| 28 | +## Detailed Setup Instructions |
| 29 | + |
| 30 | +### Step 1: Authorize Your GitLab Group with Gruntwork |
| 31 | + |
| 32 | +To use Gruntwork Pipelines with GitLab, your group needs authorization from Gruntwork: |
| 33 | + |
| 34 | +1. Email your Gruntwork account manager or [email protected] with: |
| 35 | + - Your GitLab group name(s) e.g. <CustomizableValue id="GITLAB_GROUP_NAME" /> |
| 36 | + - The GitLab instance URL (e.g., https://gitlab.com) |
| 37 | + - Your organization name |
| 38 | + |
| 39 | +2. Wait for confirmation that your group has been authorized. |
| 40 | + |
| 41 | +### Step 2: Install Required Tools |
| 42 | + |
| 43 | +First, you'll need to install [mise](https://mise.jdx.dev/), a powerful environment manager that will help set up the required tools: |
| 44 | + |
| 45 | +1. Install mise by following the [getting started guide](https://mise.jdx.dev/getting-started.html) |
| 46 | + |
| 47 | +2. Activate mise in your shell: |
| 48 | + ```bash |
| 49 | + # For Bash |
| 50 | + echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc |
| 51 | + |
| 52 | + # For Zsh |
| 53 | + echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc |
| 54 | + |
| 55 | + # For Fish |
| 56 | + echo 'mise activate fish | source' >> ~/.config/fish/config.fish |
| 57 | + ``` |
| 58 | + |
| 59 | +3. Install the boilerplate tool, which will generate the project structure: |
| 60 | + ```bash |
| 61 | + # For mise version BEFORE 2025.2.10 |
| 62 | + mise plugin add boilerplate https://github.com/gruntwork-io/asdf-boilerplate.git |
| 63 | + |
| 64 | + # For mise version 2025.2.10+ |
| 65 | + mise plugin add boilerplate |
| 66 | + |
| 67 | + |
| 68 | + ``` |
| 69 | + |
| 70 | +4. Verify the installation: |
| 71 | + ```bash |
| 72 | + boilerplate --version |
| 73 | + |
| 74 | + # If that doesn't work, try: |
| 75 | + mise x -- boilerplate --version |
| 76 | + |
| 77 | + # If that still doesn't work, check where boilerplate is installed: |
| 78 | + mise which boilerplate |
| 79 | + ``` |
| 80 | + |
| 81 | +### Step 3: Install Gruntwork Pipelines in Your Repository |
| 82 | + |
| 83 | +1. Identify where you want to install Gruntwork Pipelines, for example create a new project/repository in your GitLab group (or use an existing one) named <CustomizableValue id="REPOSITORY_NAME" /> |
| 84 | + |
| 85 | +2. Clone the repository to your local machine if it's not already cloned: |
| 86 | + ```bash |
| 87 | + git clone [email protected]: $$GITLAB_GROUP_NAME $$/ $$REPOSITORY_NAME $$.git |
| 88 | + cd $$REPOSITORY_NAME$$ |
| 89 | + ``` |
| 90 | +3. Create a new branch for your changes: |
| 91 | + ```bash |
| 92 | + git checkout -b gruntwork-pipelines |
| 93 | + ``` |
| 94 | + |
| 95 | +4. Download the sample vars.yaml file: |
| 96 | + ```bash |
| 97 | + curl -O https://raw.githubusercontent.com/gruntwork-io/terraform-aws-architecture-catalog/main/examples/gitlab-pipelines/vars.yaml |
| 98 | + ``` |
| 99 | + |
| 100 | +4. Edit the `vars.yaml` file to customize it for your environment |
| 101 | + |
| 102 | +5. `cd` to the root of <CustomizableValue id="REPOSITORY_NAME" /> where you wish to install Gruntwork Pipelines. Run the boilerplate tool to generate your repository structure: |
| 103 | + ```bash |
| 104 | + boilerplate --template-url "[email protected]:gruntwork-io/terraform-aws-architecture-catalog.git//templates/gitlab-pipelines-infrastructure-live-root/?ref=v2.12.6" --output-folder . --var-file vars.yaml --non-interactive |
| 105 | + ``` |
| 106 | + |
| 107 | + If you encounter SSH issues, verify your SSH access to GitHub: |
| 108 | + ```bash |
| 109 | + |
| 110 | + # or try cloning manually |
| 111 | + git clone [email protected]:gruntwork-io/terraform-aws-architecture-catalog.git |
| 112 | + ``` |
| 113 | + |
| 114 | +6. Commit the changes: |
| 115 | + ```bash |
| 116 | + git add . |
| 117 | + git commit -m "[skip ci] Add Gruntwork Pipelines" |
| 118 | + git push origin gruntwork-pipelines |
| 119 | + ``` |
| 120 | + |
| 121 | +7. Create a merge request in GitLab and review the changes. |
| 122 | + |
| 123 | +### Step 4: Install AWS OIDC Provider and IAM Roles for Pipelines |
| 124 | + |
| 125 | + |
| 126 | +1. Navigate to the `_global` folder under each account in your repository and review the Terraform files that were created: |
| 127 | + - The GitLab OIDC identity provider in AWS |
| 128 | + - IAM roles for your the account (`root-pipelines-plan` and `root-pipelines-apply`) |
| 129 | + |
| 130 | +2. Apply these configurations to create the required AWS resources: |
| 131 | + ```bash |
| 132 | + cd $ACCOUNT/_global/ |
| 133 | + terragrunt run-all plan |
| 134 | + terragrunt run-all apply |
| 135 | + ``` |
| 136 | + |
| 137 | + |
| 138 | +### Step 5: Complete the Setup |
| 139 | + |
| 140 | +1. Return to GitLab and merge the merge request with your changes. |
| 141 | +2. Ensure the `PIPELINES_GITLAB_TOKEN` (and optionally, `PIPELINES_GITLAB_READ_TOKEN`) is set as a CI/CD variable to your group if you haven't already (see the [Machine Users setup guide](/2.0/docs/pipelines/installation/viamachineusers#gitlab) for details) |
| 142 | +3. Test your setup by creating a new branch with some sample infrastructure code and creating a merge request. |
| 143 | + |
| 144 | +## Next Steps |
| 145 | + |
| 146 | +After setting up Pipelines, you can: |
| 147 | + |
| 148 | +- [Deploy your first infrastructure change](/2.0/docs/pipelines/tutorials/deploying-your-first-infrastructure-change) |
| 149 | +- [Learn how to run plan and apply operations](/2.0/docs/pipelines/guides/running-plan-apply) |
| 150 | +- [Extend Pipelines with custom actions](/2.0/docs/pipelines/guides/extending-pipelines) |
| 151 | + |
| 152 | +## Troubleshooting |
| 153 | + |
| 154 | +If you encounter issues during setup: |
| 155 | + |
| 156 | +- Ensure your GitLab CI user has the correct permissions to your group and projects |
| 157 | +- Verify the `PIPELINES_GITLAB_TOKEN` is set correctly as a CI/CD variable and is *NOT* marked as protected |
| 158 | +- Confirm your GitLab group has been authorized by Gruntwork for Pipelines usage |
| 159 | + |
| 160 | +For further assistance, contact [[email protected]](mailto:[email protected]). |
0 commit comments