External Client Code Sync

This guide explains how to configure your project to automatically sync code to external client repositories while protecting internal configurations.

Overview

Features

The external sync capability provides:

1. Automatic code sync to external repositories (e.g., client's GitHub)
2. Internal pipeline configuration exclusion
3. Manual trigger controls
4. Support for main branch and tag syncs

Setup Instructions

1. Update Pipeline Configuration

Add the sync template to your project's .gitlab-ci.yml:

include:
  # Main pipeline (required)
  - project: 'stratpoint/engineering-standards'
    ref: main
    file: 'pipelines/ci/gitlab/.gitlab-ci.yml'

  # External sync capability (optional)
  - project: 'stratpoint/engineering-standards'
    ref: main
    file: 'pipelines/ci/gitlab/templates/sync/code-sync.yml'

2. Configure CI/CD Variables

Set these variables in your GitLab project's CI/CD settings (Settings > CI/CD > Variables):

Variable	Description	Example
EXTERNAL_REPO_URL	URL of the external repository	https://github.com/client/repo.git
EXTERNAL_REPO_BRANCH	Target branch in external repository	main
EXTERNAL_TOKEN	Access token for external repository	GitHub Personal Access Token
GIT_AUTHOR_NAME	Name to use for sync commits (optional)	Client Team
GIT_AUTHOR_EMAIL	Email to use for sync commits (optional)	team@client.com

Git Author Configuration

• If GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL are not set, commits will use your GitLab user details
• Set these variables when commits need to appear from a client-specific identity
• Useful when syncing to client repositories where commit attribution is important

Access Token Setup

GitHub Token Setup

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Create a token with repo scope
3. Copy the token value
4. Add it as EXTERNAL_TOKEN in GitLab CI/CD variables

Bitbucket Token Setup

1. Go to Bitbucket Settings > Access tokens
2. Create a token with repository write access
3. Copy the token value
4. Add it as EXTERNAL_TOKEN in GitLab CI/CD variables

3. Using the Sync Pipeline

Once configured, you'll see two new manual jobs in your pipeline:

Available Jobs

1. sync:external:main

   1. Appears when changes are made to main branch
   2. Manually trigger to sync main branch changes
   3. Use for regular updates

2. sync:external:tag

   1. Appears when a new tag is created
   2. Manually trigger to sync tagged releases
   3. Use for version releases

How It Works

Sync Process

Process Steps

1. Pipeline creates a clean git repository
2. Adds all project files
3. Explicitly excludes .gitlab-ci.yml
4. Creates a commit with [skip ci] tag
5. Force pushes to external repository

File Exclusion

Excluded Files

The following files are automatically excluded from sync:

1. .gitlab-ci.yml (Internal pipeline configuration)
2. Any other files that should remain internal

Best Practices

Sync Timing

1. Sync after successful deployment
2. Sync tagged releases for versioning
3. Use manual triggers to control timing

Branch Management

1. Keep external branch names consistent
2. Use main/master based on client preference
3. Consider branch protection rules

Security

1. Use dedicated service accounts for tokens
2. Regularly rotate access tokens
3. Monitor sync job logs

Troubleshooting

Common Issues

Authentication Failures

1. Verify token has correct permissions
2. Check token hasn't expired
3. Ensure token is properly set in CI/CD variables

Sync Conflicts

1. Check external repository isn't modified directly
2. Verify branch names match
3. Review force push permissions

Missing Files

1. Confirm files are committed in source
2. Check .gitignore rules
3. Verify file paths

Support

Need Help?

If you encounter issues:

1. Check pipeline job logs
2. Review variable configuration
3. Contact Systems Engineering team

Maintenance

Regular Tasks

Periodic Maintenance

1. Review and rotate access tokens
2. Monitor sync job success rates
3. Update external repository configurations

Security Considerations

Security Checklist

1. Use dedicated service accounts
2. Regularly audit access permissions
3. Monitor external repository activity