Skip to main content
SmoothGlue Logo
In this section

Use the Pillars pipeline in your project

How-ToPublicInterface: GitLab

When you need this​

Use this guide to add Pillars of Creation to an existing GitLab project or inspect a project's shared-pipeline configuration. Confirm what is already configured before adding another include or changing project settings.

Before you begin​

You need the following:

  • Maintainer access for the project settings used in this procedure, or assistance from a maintainer.
  • The working Pillars include already configured for your project, or the customer-accessible template location and approved ref supplied by your platform team.
  • Suitable runners enabled for your project, including access to the required images.
  • The application files and build configuration expected by its framework.
  • Credentials and permissions for the optional integrations you intend to use.

For SmoothGlue shared runners, confirm that Settings > CI/CD > Runners allows the project to use the instance runners. Your installation can have additional runner or network requirements.

Add the pipeline include​

  1. Create a branch for the onboarding change.

  2. Create or edit .gitlab-ci.yml at the repository root. Keep an existing working include. For a new project, replace your-org/pillars-template and APPROVED_REF with the location and revision supplied by your platform team:

    include:
      - project: "your-org/pillars-template"
        ref: "APPROVED_REF"
        file: "pipeline/pipeline.yaml"

  3. Preserve any project-specific jobs and settings that you still need. Review the combined pipeline configuration before opening a merge request.

You do not need to inspect or maintain the Pillars implementation repository. GitLab still needs permission to resolve the supplied template when creating the pipeline. If an include reports access denied, ask the platform team to repair the customer template delivery. A secret set inside a job cannot fix an include that fails before jobs are created. The configuration reference explains that distinction.

Configure framework and analysis jobs​

Before running the pipeline, identify the jobs selected by your application files. For example, package-lock.json selects npm support and go.mod selects Go support unless the corresponding switch disables it.

If a repository contains an npm lockfile only for tooling, disable the npm application jobs by adding a project CI/CD variable with key NPM and value false. Framework include controls must be set before YAML merging; see where to set configuration.

See the framework selection table for the available switches. Framework includes and individual jobs can have different conditions. Use the framework job reference for prerequisites, commands, disable switches, and outputs. Several build jobs also publish to staging; configure that destination before running them.

Configure SonarQube with an analysis token and properties file. Use the analysis reference to configure other selected scanners and application tests. A Dockerfile can select Cypress and ZAP even when the application does not provide their required test setup. Disable inapplicable jobs explicitly and preserve the prerequisites of enabled jobs.

Verify the pipeline is working​

Commit the configuration on your onboarding branch and open a merge request. Use the merge-request pipeline for these checks; the corresponding branch push pipeline can be suppressed to avoid a duplicate run.

  1. Confirm that the merge-request pipeline was created and its jobs can use a runner.
  2. Confirm that the expected framework jobs and applicable analysis jobs are present.
  3. If a Dockerfile is configured, inspect container-image and the image reference passed to the artifact-analysis jobs.
  4. Review job logs for configuration failures and scan findings. Check skipped jobs and allowed failures as well as failed jobs.
  5. If Syft runs, confirm that its artifacts contain the expected SBOM files. Evidence archives and release attachments are separate jobs with separate conditions.

A passing pipeline establishes the outcome of its selected checks. It does not imply that every tool ran or that the image is approved for production.

Configure optional release jobs​

Set up these permissions when you intend to create releases or attach their artifacts. For job conditions and outputs, see the release reference.

Configure release permissions​

If you use the shared release workflow, enable Allow Git push requests to the repository under Settings > CI/CD > Job token permissions. Confirm that the project's branch protection and release policy permit the intended operation.

The semantic-release job sets GITLAB_TOKEN to CI_JOB_TOKEN by default. Its optional GPG-signing path uses RELEASE_TOKEN instead. Test release permissions using your approved release procedure.

Configure the release token​

The attach-artifacts job requires RELEASE_TOKEN when that job runs. The same variable is needed for the optional signing path described above.

  1. Create a project access token with the api scope and the role required for the intended release operations.
  2. Store it as a masked CI/CD variable named RELEASE_TOKEN.
  3. Apply protection and environment scope according to the refs that are allowed to release. Confirm that those rules make the token available to the intended job.

If your project does not use release attachments, set ATTACH_ARTIFACTS: "false". Disabling that job does not disable the separate release-signing requirement.

Configure optional Kustomize updates​

For manifests in a separate project, the shared pipeline can expose a manual downstream trigger. The target project must include the appropriate Pillars configuration and permit the required job-token access and Git push operations.

warning

The default update workflow pushes directly to the selected branch. It does not create a merge request. Use a branch and review process appropriate for the environment that consumes these manifests.

Add KUSTOMIZE_PROJECT and KUSTOMIZE_BRANCH as project CI/CD variables with the approved destination values. Set the update values on the trigger job in .gitlab-ci.yml, replacing the example image and tag with a verified, already published image:

trigger-update-kustomize-image:
  variables:
    KUSTOMIZE_IMAGE_UPDATE: "true"
    KUSTOMIZE_FILES: "overlays/dev/kustomization.yaml"
    KUSTOMIZE_IMAGE_NAME: "registry.example.com/example/application"
    KUSTOMIZE_IMAGE_TAG: "1.2.3"

These values belong on the named trigger because it restricts top-level YAML variable inheritance. It also does not import the build job's resolved image coordinates.

The trigger-update-kustomize-image job is manual when the target project and branch are configured and the feature is not disabled. Review the image and target before starting it. The target update job changes matching image tags, commits the changes, and pushes to the configured branch.

See the complete Kustomize settings and limitations before enabling this workflow, including the current image-job dependency mismatch.

Recover from an onboarding failure​

Correct include access, runner availability, or integration settings according to the failed job's log, then run a new pipeline for a configuration change. Follow Troubleshoot Pillars for the specific failure. If the new configuration prevents required project jobs from running, revert the onboarding commit and reintroduce the change after reviewing the combined pipeline.

Reverting .gitlab-ci.yml does not undo project settings, revoke tokens, or reverse a manifest update that was already pushed to another project. Review those changes separately.

Learn more​