Building With Private Repositories

Building with Private Repositories

This guide covers how to build Dynamic Devices Yocto layers when recipes access private repositories, such as the eink-spectra6 userspace library.

Overview

Some recipes in the meta-dynamicdevices layers access private GitHub repositories that require SSH key authentication. The build system uses kas-container which runs in Docker, so SSH keys must be properly forwarded from the host to the container.

Prerequisites

1. SSH Key Setup

Ensure you have SSH keys configured for GitHub access:

# Test GitHub SSH access
ssh -T git@github.com

Expected output:

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

If this fails, you need to:

1. Generate SSH keys: ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
2. Add the public key to your GitHub account
3. Test the connection again

2. SSH Agent

The SSH agent must be running and have your key loaded:

# Start SSH agent (if not running)
eval "$(ssh-agent -s)"

# Add your SSH key
ssh-add ~/.ssh/id_rsa  # or your specific key file

# Verify key is loaded
ssh-add -l

Expected output:

4096 SHA256:... your_email@example.com (RSA)

Build Process

Automatic SSH Forwarding

The Dynamic Devices build scripts automatically handle SSH key forwarding:

# Build with automatic SSH forwarding
KAS_MACHINE=imx93-jaguar-eink ./scripts/kas-build-base.sh

What happens automatically:

• ✅ Detects SSH agent ($SSH_AUTH_SOCK)
• ✅ Forwards SSH agent to container (--ssh-agent)
• ✅ Mounts SSH directory (--ssh-dir ~/.ssh)
• ✅ Sets proper permissions in container
• ✅ Handles GitHub host key verification

Manual Verification

You can verify SSH access works in the container:

# Enter container shell
./scripts/kas-shell-base.sh

# Inside container, test GitHub access
ssh -T git@github.com

Troubleshooting

Common Issues and Solutions

1. "Host key verification failed"

Problem: Container doesn't trust GitHub's host key.

Solution: This is handled automatically by kas-container's SSH forwarding.

2. "Permission denied (publickey)"

Problem: SSH key not accessible in container.

Diagnosis:

# Check SSH agent on host
echo $SSH_AUTH_SOCK
ssh-add -l

# Check SSH access on host
ssh -T git@github.com

Solutions:

• Ensure SSH agent is running: eval "$(ssh-agent -s)"
• Add your key: ssh-add ~/.ssh/id_rsa
• Verify key permissions: chmod 600 ~/.ssh/id_rsa

3. "SSH_AUTH_SOCK not set"

Problem: SSH agent not running.

Solution:

# Start SSH agent
eval "$(ssh-agent -s)"

# Add key
ssh-add ~/.ssh/id_rsa

# Verify
echo $SSH_AUTH_SOCK

4. Container SSH Issues

Debug in container:

# Enter container
./scripts/kas-shell-base.sh

# Check SSH agent in container
echo $SSH_AUTH_SOCK
ssh-add -l

# Test GitHub access
ssh -T git@github.com

Advanced Troubleshooting

SSH Directory Permissions

Ensure correct permissions on host:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
chmod 644 ~/.ssh/known_hosts

Multiple SSH Keys

If you use multiple SSH keys, ensure the correct one is loaded:

# List loaded keys
ssh-add -l

# Add specific key
ssh-add ~/.ssh/id_rsa_github

# Test with specific key
ssh -i ~/.ssh/id_rsa_github -T git@github.com

SSH Config

You can use SSH config for complex setups:

# ~/.ssh/config
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_github
    IdentitiesOnly yes

CI/CD Integration

GitHub Actions

For automated builds in GitHub Actions:

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

- name: Build with Private Repos
  run: |
    KAS_MACHINE=imx93-jaguar-eink ./scripts/kas-build-base.sh

GitLab CI

For GitLab CI/CD:

before_script:
  - eval $(ssh-agent -s)
  - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
  - mkdir -p ~/.ssh
  - chmod 700 ~/.ssh

build:
  script:
    - KAS_MACHINE=imx93-jaguar-eink ./scripts/kas-build-base.sh

Jenkins

For Jenkins with SSH Agent plugin:

sshagent(['github-ssh-key']) {
    sh 'KAS_MACHINE=imx93-jaguar-eink ./scripts/kas-build-base.sh'
}

Private Repository Recipes

Current Private Repositories

The following recipes access private repositories:

Recipe	Repository	Purpose
eink-spectra6	git@github.com:DynamicDevices/eink-spectra6.git	Spectra 6 E-Ink display userspace library
spi-lib	git@github.com:DynamicDevices/spi-lib.git	SPI library for radar presence detection

Adding New Private Repository Recipes

When creating recipes for private repositories:

1. Use SSH protocol:

   SRC_URI = "git://git@github.com/DynamicDevices/my-private-repo.git;protocol=ssh;branch=${SRCBRANCH}"

2. Disable mirror tarballs:

   BB_GENERATE_MIRROR_TARBALLS = "0"

3. Use machine features for conditional inclusion:

   COMPATIBLE_MACHINE = "${@bb.utils.contains('MACHINE_FEATURES', 'my-feature', '${MACHINE}', 'null', d)}"

Security Considerations

Best Practices

1. Use Deploy Keys: For CI/CD, use repository-specific deploy keys instead of personal SSH keys
2. Limit Key Access: Use keys with minimal required permissions
3. Key Rotation: Regularly rotate SSH keys used in CI/CD
4. Audit Access: Monitor repository access logs

Container Security

The kas-container SSH forwarding:

• ✅ Mounts SSH directory read-only
• ✅ Uses temporary SSH agent socket
• ✅ Doesn't persist SSH keys in container images
• ✅ Isolates SSH access to build process only

FAQ

Q: Why not use HTTPS with tokens?

A: SSH keys provide better security and are easier to manage in containerized build environments. Personal access tokens have broader permissions and are harder to scope appropriately.

Q: Can I build without private repository access?

A: Yes, but recipes that depend on private repositories will be skipped. Use machine features to control which recipes are included:

# Build without E-Ink support (skips eink-spectra6)
MACHINE_FEATURES:remove = "el133uf1"

Q: How do I know which recipes need private access?

A: Check the build logs for SSH-related errors, or look for recipes with protocol=ssh in their SRC_URI.

Q: Does this work with other Git hosting services?

A: Yes, the same principles apply to GitLab, Bitbucket, or any SSH-based Git service. Just ensure your SSH keys are configured for the appropriate service.

Related Documentation

• KAS Container Documentation
• GitHub SSH Key Setup
• Yocto Fetcher Documentation
• Build Scripts: See scripts/ folder in project root for build automation

---

For additional support with private repository builds, please open an issue with details about your SSH setup and any error messages.