Getting Started - Preparing for the Pipeline Queue
Overview
Product teams must meet certain prerequisites before MDO can place their COT epic in the pipeline queue. Additional items are suggested and must be addressed eventually, but they do not bar initial pipeline implementation. Use this document to guide you through the necessary actions to prepare for the pipeline queue.
NOTE
P1 GitLab email notifications are disabled globally due to cyber compliance requirements. At this time, P1 cannot enable notifications due to security concerns. Users must rely on the platform UI or approved integrations for updates.
Hard Prerequisites
The following items must be completed before MDO begins implementing a pipeline.
Confirm Registration for Services
The P1 Onboarding team will register all users for the services listed below during your team’s onboarding. Your team's OS can register team members who join after initial onboarding.
To confirm that you have a funded project and are eligible for application access, provide your PBO, CTT, or COT reference number to the P1 Onboarding team. They will validate this information internally.
Meet GitLab Requirements
URL Slug Requirements
A URL slug is the part of a web address that comes after the last slash (/) and uniquely identifies a page. URL slugs must include:
- Team name
- Application name: This is a GitLab group and represents the application.
- Repository/service name: This is a GitLab project and corresponds with the service/deployment for a Docker image. For package-pipelines, this repository produces a package/artifact that can be used by other pipelines/repositories.
NOTE Remember
Organizations are composed of many teams, each of which may contain one or more apps. Each app may comprise one or more repositories (i.e., microservices, packages), and all repositories with an image within an application will be deployed in Kubernetes, with the application's URL slug set as the namespace.
Group and Repository Naming Requirements
GitLab group (organization, team, app) and project (repository) names must meet the following criteria:
- Contain between 3 and 18 characters, inclusive.
- Contain only lowercase characters, numbers, and dashes.
- Start with an alphabetical character.
Project Structure Requirements
The project structure group/subgroup/project is required. A P1 DevOps Engineer will create your initial GitLab group and assign a team owner at the group level. That team owner controls future access at the GitLab group, subgroup, or project level.
Verify Repository Requirements
Repository requirements provide a baseline setup for every project. Your code repository must follow these standards. Party Bus assumes there will be a minimum of a front-end project and a back-end project for each application.
Each repository may have only one pipeline configuration, one Dockerfile, and one deployment. All code in a repository must be part of the same deployment package. Applications that consist of multiple services must be split into separate repositories, with one service per repository. Party Bus does not support:
- Multi-language repositories,
- Multi-image repositories,
- Multi-package repositories, or
- Monolithic repositories (monorepos).
Pipeline templates are designed to build, scan, and deploy one language/framework combination per repository.
Recommendation: Include a README file for each application, explaining the purpose of each project and your overall application.
Repository Clean-Up
Repositories must only contain code to be deployed. Along with the monorepo and multiple-language requirements, you must remove extraneous code or scripts not used for local development or deployment (i.e., Terraform scripts, Kubernetes manifests, and other unrelated code).
Tech Stack Requirements
Verify each repository uses a tech stack that is currently supported. Images/software versions are subject to change. Recommended versions depend on Iron Bank images. If a different version is needed, verify it is supportable and let MDO know when requesting a pipeline by including this information in the request form.
| Tech Stack/ Package Manager | Image | Deployment Pipeline Support | Package Pipeline Support | Notes |
|---|---|---|---|---|
| dotnet | registry1.dso.mil/ironbank/redhat/dotnet-core/dotnet-sdk-6.0:6.0 | YES | YES | |
| go | registry1.dso.mil/ironbank/google/golang/ubi9/golang-1.21:1.21.8 | YES | YES | |
| gradle | registry1.dso.mil/ironbank/opensource/gradle/gradle-jdk11:8.1 | YES | YES | |
| maven | registry1.dso.mil/ironbank/opensource/maven/maven-openjdk-11:3.8.6 | YES | YES | |
| npm/yarn | registry1.dso.mil/ironbank/opensource/nodejs/nodejs16:16.20.2 | YES | YES | |
| php | registry.il2.dso.mil/platform-one/devops/pipeline-templates/base-image/php74-composer:7.4.29 | YES | YES | Based on composer |
| python | registry.il2.dso.mil/platform-one/devops/pipeline-templates/pipeline-job/python39-builder:3.9.18 | YES | YES | Based on pip requirements.txt; supports pytest and coverage unit testing |
Meet Cyber Compliance Requirements
Project Visibility Requirements
Project visibility settings protect your project from security concerns such as being discovered via your favorite search engine or being cloned over HTTPS without authentication. You must set all P1 projects to Internal or Private. If you don't mind sharing, Internal is preferred.
Internal projects can be seen and cloned by any authenticated users for internal sharing.
Private projects can only be viewed/cloned by project members. Personal private repositories under the user namespace are not allowed.
By default, all GitLab groups created for each team are set to Private. The visibility level cascades to the projects created under the GitLab group.
Default Branch Requirements
Default branch protection and role enforcement are cybersecurity best practices to enforce code validation and pushes to the default branch.
By default, defining branches as protected provides the following features:
- Prevents its creation, if not already created, from everybody except users with Maintainer permission.
- Prevents pushes from everybody except users with Allowed permission.
- Prevents anyone from force pushing to the branch.
- Prevents anyone from deleting the branch.
To ensure the default branch is protected, P1 enforces the following roles:
- Only Maintainers can merge to default.
- No one can push directly to default.
How to Protect Manually Created Branches
Follow these steps to protect manually created branches:
- Navigate to Settings > Repository > Protected Branches.
- Select Add protected branch.
- Select your branch.
- Select Developers + Maintainers in the drop down menu for Allowed to merge.
- Select Developers + Maintainers in the drop down menu for Allowed to push and merge.
- Do not allow to force push.
- Do require approval from code owners.
- Select Protect.
Pipeline Requirements
Pipelines are created and managed by the MDO team.
Requirements
No
gitlab-ci.yamlallowed.Pipelines deployed to P1 staging or production environments must not have the GitLab feature allow_failures enabled.
MDO uses templates to define which jobs must be executed for a pipeline. Each template is language-specific/technology-specific. Pipeline jobs are defined in Pipeline Basics. We support two broad types of pipelines:
Meet Dockerfile Requirements
Example Dockerfiles can be found here.
IMPORTANT:
Dockerfiles MUST be at the root of each project. Each project is deployed, and the Dockerfile sets the initial requirements.
Requirements
Product images built in a Party Bus pipeline are required to be built with an approved Iron Bank-hardened image.
a. Approved images can be found in Registry1 Harbor or the Container Registry (search for base-image).
b. Never use the :LATEST. Always use a specific :< TAG >.
Dockerfiles are not allowed to contain commands that will modify the base image (e.g., 'yum update,' and 'yum install' are not allowed). Dependencies and config files can be copied into the Docker image, but if the base image lacks the necessary OS-level dependencies, a ticket should be opened to request a custom image.
Using New Iron Bank–Approved Images
A new image is an image that does not exist in the Iron Bank hardened images repository. The Iron Bank team is the approval authority for custom images.
Using New MDO Images
Images created by the MDO team are a rare exception. We recommend contacting Iron Bank before requesting a custom image from the MDO team. Examples of the types of custom images would be add-ons to or a new version of an existing image. Open a (Pipeline Issues ticket ) to request a modification to an existing image. You can find more detailed information in the Docker How-To articles.
Verify Code Is Checked in Correctly
Verify that the code is checked into the repository's default branch. Party Bus pipelines are configured to only run the full pipeline on the default branch. Other protected branches can run the scan and build jobs, but cannot deploy.
Access SonarQube
Each user requiring SonarQube access should log in to SonarQube (IL2 | IL4 | IL5 ) to initialize their account. Their account will then be associated with the relevant projects by MDO when setting up the pipelines.
Verify Product Team Access
Verify that your team can access the respective Atlassian and GitLab groups.
Receive Signed Certificate to Field
MDO will not begin work or place the COT epic in the pipeline queue until your team has received a signed CtF. Learn more about the Path to CtF.
Provide COT Description Details
In a comment on the COT, provide the following information:
- Staging environment (choices: IL2, IL4, IL5). This will be the same IL as the source code repository.
- Production environment(s) (choices: IL2, IL4, IL5, JWICS, SIPR)
- List of users who need access to SCA tools (GitLab SAST and SonarQube). They can view scan results and comment on whitelisting findings. Access to Twistlock or Anchore is not included; failures are only visible in pipeline job output. For each user, include the following in the COT comment:
- P1 username
- First and last name
- Email address
Soft Prerequisites
The following items will need to be addressed eventually, but their incomplete status does not bar initial pipeline implementation.
Define NPM/Yarn Scripts
If the repository is using the npm or yarn pipeline template, define the following scripts in package.json:
- test:unit (runs in unit tests job)
- lint (runs in lint job)
- test:e2e-ci (runs in e2e tests job if using Cypress)
Configure Dockerfile Properly
If the repository will create a Docker image, ensure the Dockerfile is properly configured:
- Place the Dockerfile at the root of the repository.
- Lint the Dockerfile using hadolint, and fix all warnings or errors.
- Ensure the Dockerfile contains no install commands (e.g., pip install, apt-get install, dnf, yum, among others), as P1 prohibits egress in the Dockerfile. Dependencies are installed through the pipeline's build stage and should be copied into the image after they are scanned.
Related Content and References
Submit Requests to the Help Desk
- Report a Pipeline Issue to the Help Desk
- Submit a Pipeline Request Ticket
- Request Application Access Updates
- Request to Add/Remove User Access