Authentication

Copybara needs authentication to read from origins and write to destinations.

Authentication Methods

Method	Use Case	Security
Personal Access Token (Classic)	Quick setup	Medium
Fine-Grained Token	Scoped access	High
SSH Key	Traditional Git auth	Medium
Deploy Key	Single repo write	High
GitHub App	Enterprise automation	High

Personal Access Token (Classic)

Setup

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click “Generate new token (classic)”
3. Select scopes:
   • repo (full repository access)
   • workflow (if modifying workflows)
4. Generate and copy the token

See GitHub’s token documentation for details.

Usage

Configure Git to use your token via the credential helper:

# Enable credential storage
git config --global credential.helper store

# Git will prompt for credentials on first use
# Username: x-access-token
# Password: <your-token>

In GitHub Actions, use the built-in GITHUB_TOKEN or configure credentials via environment:

- name: Configure Git
  env:
    GH_TOKEN: ${{ secrets.PAT }}
  run: |
    git config --global credential.helper '!f() { echo "username=x-access-token"; echo "password=${GH_TOKEN}"; }; f'

Fine-Grained Token (Recommended)

More secure than classic tokens with repository-scoped access:

Setup

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click “Generate new token”
3. Set expiration
4. Select repository access: “Only select repositories”
5. Choose the destination repository
6. Set permissions:
   • Contents: Read and write
   • Pull requests: Read and write
   • Metadata: Read

Usage

Same credential helper approach as classic tokens:

git config --global credential.helper store
# Git prompts for credentials on first authenticated operation

Tip

Fine-grained tokens can be scoped to specific repositories, limiting blast radius if compromised.

SSH Key

Traditional Git authentication using SSH:

Setup

1. Generate SSH key:

   ssh-keygen -t ed25519 -C "copybara@example.com" -f ~/.ssh/copybara_key

2. Add public key to GitHub:

   • Settings → SSH and GPG keys → New SSH key
   • Or repository Settings → Deploy keys (for single repo)

See GitHub’s SSH documentation for complete setup.

Usage

# Add key to SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/copybara_key

# Or specify key file directly
GIT_SSH_COMMAND="ssh -i ~/.ssh/copybara_key" java -jar copybara.jar ...

In GitHub Actions:

- name: Configure SSH
  uses: webfactory/ssh-agent@v0.9.0
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

Use SSH URL in config:

destination = git.destination(
    url = "git@github.com:org/repo.git",
    push = "main",
)

Deploy Key

SSH key scoped to a single repository:

Setup

1. Generate SSH key:

   ssh-keygen -t ed25519 -C "copybara-deploy" -f ~/.ssh/deploy_key

2. Add to repository:

   • Repository Settings → Deploy keys
   • Add deploy key (paste the .pub file contents)
   • Enable “Allow write access”

Usage

- name: Configure Deploy Key
  uses: webfactory/ssh-agent@v0.9.0
  with:
    ssh-private-key: ${{ secrets.DEPLOY_KEY }}

Note

Deploy keys only work for one repository. Use a GitHub App or PAT for multi-repo workflows.

GitHub App

Best for enterprise and multi-repo automation:

Setup

1. Create GitHub App:

   • Organization Settings → Developer settings → GitHub Apps
   • New GitHub App
   • Set permissions:
     • Contents: Read and write
     • Pull requests: Read and write
     • Metadata: Read
   • Install on required repositories

2. Note the App ID and generate a private key

See GitHub Apps documentation for complete setup.

Usage

- name: Generate token
  id: app-token
  uses: actions/create-github-app-token@v1
  with:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
    repositories: destination-repo

- name: Configure Git
  env:
    GH_TOKEN: ${{ steps.app-token.outputs.token }}
  run: |
    git config --global credential.helper '!f() { echo "username=x-access-token"; echo "password=${GH_TOKEN}"; }; f'

GitLab Authentication

For GitLab repositories, create a personal access token:

1. Go to User Settings → Access Tokens
2. Create token with scopes: read_repository, write_repository
3. Use oauth2 as username with your token as password

See GitLab token documentation.

Gerrit Authentication

For Gerrit destinations, generate an HTTP password:

1. Go to Gerrit Settings → HTTP Credentials
2. Generate new password
3. Configure Git credential helper with your username and HTTP password

Security Best Practices

1. Use fine-grained tokens when possible
2. Limit scope to only required repositories
3. Set expiration on tokens (30-90 days recommended)
4. Rotate regularly (especially after team changes)
5. Use CI/CD secrets - never commit credentials to repositories
6. Audit access periodically via GitHub/GitLab audit logs
7. Use GitHub Apps for production automation

Caution

Never commit tokens or credentials to your repository. Always use CI/CD secret management (GitHub Secrets, GitLab CI Variables, etc.).

Troubleshooting

”Authentication failed”

• Verify token hasn’t expired
• Check token has required scopes (repo for full access)
• Test with: git ls-remote <repository-url>
• For fine-grained tokens, verify the repository is selected

”Permission denied (publickey)”

• Verify SSH key is added to ssh-agent: ssh-add -l
• Test SSH connection: ssh -T git@github.com
• Check key is added to GitHub/GitLab

”Host key verification failed”

Add the host to known hosts:

ssh-keyscan github.com >> ~/.ssh/known_hosts
ssh-keyscan gitlab.com >> ~/.ssh/known_hosts

Token Scope Reference

Operation	Required GitHub Scope
Read public repo	(none)
Read private repo	repo
Push to repo	repo
Create pull request	repo
Modify GitHub Actions	repo, workflow

Next Steps

• GitHub Actions setup
• Automation patterns