Managing Sensitive Information with Secrets

This document introduces how to create encrypted Secrets at the organization and project levels, securely reference them in workflows, and understand their log masking and Fork isolation mechanisms.

Pipelines often require sensitive information such as passwords, API keys, and access credentials, but you don't want to hardcode them into workflow files or code repositories.

Configuration Instructions

Creating a Secret

Organization-level Secret:

1. Go to Organization Settings → Keys and Variables → Organization Secrets.
2. Click New Organization Secret.
3. Enter Name (e.g., PROD_DEPLOY_KEY) and Value.
4. Click Create Secret.

Project-level Secret:

1. Go to Project Settings → Keys and Variables → Repository Secrets.
2. Click New Repository Secret.
3. Enter Name and Value.
4. Click Create Secret.

Referencing a Secret in a Workflow

# .gitcode/workflows/deploy.yml
stages:
  deploy:
    name: Deployment
    jobs:
      name: push-to-prod
      runs-on: {ubuntu-24,x64,medium}
      steps:
        - run: |
            ssh -i ${{ secrets.PROD_DEPLOY_KEY }} \
              user@prod-server.example.com \
              "deploy.sh ${{ secrets.PROD_API_TOKEN }}"

The referencing syntax is ${{ secrets.SECRET_NAME }}, and the rules for Secret names are:

• Only uppercase letters, numbers, and underscores are allowed
• Must not start with ATOMGIT_ (to avoid conflict with system variables)
• Must not start with a number

Using a Secret in Container Credentials

jobs:
  private-image-build:
    name: private-image-build
    runs-on: {ubuntu-24,x64,medium}
    container:
      image: registry.example.com/myapp:latest
      credentials:
        username: ${{ secrets.REGISTRY_USERNAME }}
        password: ${{ secrets.REGISTRY_PASSWORD }}

Secret Security Mechanisms

Security Measures	Description
Log Masking	Secret values are automatically replaced with *** in logs
Not Viewable	The original value cannot be viewed in the interface after creation, only updated or overwritten
Fork Isolation	Workflows triggered by pull_request from a forked repository cannot access project-level Secrets
Environment Approval	Environment-level Secrets can be configured with approvers; jobs cannot access them without approval

Important: In the case of a pull_request event, workflows triggered by PRs from forked repositories cannot read project Secrets. This is part of the security isolation mechanism. If you need to use Secrets in a PR pipeline, please use the pull_request_target event.