Accessing Project Dependencies

In Unity projects, managing dependencies is crucial for maintaining a clean and efficient workflow. Here, we will discuss two common types of dependencies: Unity package references using Git HTTPS and Git submodules.

Unity Package References Using Git HTTPS

Unity allows you to reference packages directly from a Git repository using HTTPS.

Example Git HTTPS Reference in `manifest.json`

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git"
  }
}

This works fine if the repository is public, but if it is private, Unity Package Manager needs Git credentials when Unity resolves the package. Setting a token on actions/checkout only authenticates the repository checkout; it does not authenticate Git operations that UPM runs later.

How to access a private Git HTTPS dependency

Allow Personal Access Tokens: If the dependency is owned by a GitHub organization, ensure that the dependency’s organization allows the use of personal access tokens. Go to the organization’s settings and look under Third-party access > Personal access tokens.
Generate a Personal Access Token: In your user settings, navigate to Developer settings > Personal access tokens and create a personal access token in GitHub with repo read access to the private package repositories.
Add Secrets: Add the token and the token owner’s GitHub username as secrets in the Unity project’s repository or organization. Go to Settings > Secrets and variables > Actions. The example below uses CI_TOKEN and CI_TOKEN_USER.
Configure Git Before Unity Runs: Add a Git URL rewrite step before buildalon/unity-action, then remove it afterward:

  - name: Configure GitHub auth for UPM git dependencies
    shell: bash
    run: |
      git config --global url."https://${{ secrets.CI_TOKEN_USER }}:${{ secrets.CI_TOKEN }}@github.com/".insteadOf "https://github.com/"

  - uses: buildalon/unity-action@v3
    name: Project Validation
    with:
      log-name: project-validation
      build-target: ${{ matrix.build-target }}
      args: -quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject

  - name: Cleanup GitHub auth for UPM git dependencies
    if: always()
    shell: bash
    run: |
      git config --global --unset-all url."https://${{ secrets.CI_TOKEN_USER }}:${{ secrets.CI_TOKEN }}@github.com/".insteadOf
      printf "protocol=https\nhost=github.com\n\n" | git credential-manager erase || true

Unity Package References Using Git SSH

Unity allows you to reference packages directly from a Git repository using SSH. This method is useful for including external libraries or shared codebases.

Example Git SSH Reference in `manifest.json`

{
  "dependencies": {
    "com.mycompany.mypackage": "ssh://git@mycompany.github.com/gitproject/com.mycompany.mypackage.git"
  }
}

How to access a private Git SSH dependency

Generate an SSH Key: Generate an SSH key pair and add the public key to a GitHub user or deploy key that can read the private package repository. For CI, use a key with the least access needed that can be loaded non-interactively.
Add the Private Key as a Secret: Add the private key as a secret to the Unity project’s repository or organization. Go to Settings > Secrets and variables > Actions. The example below uses SSH_PRIVATE_KEY.
Start an SSH Agent Before Unity Runs: Add the key to an SSH agent before buildalon/unity-action, then stop the agent afterward. Setting ssh-key on actions/checkout only authenticates Git operations that use checkout’s local Git config; UPM resolves packages later through Git and SSH.

  - name: Configure SSH auth for UPM git dependencies
    shell: bash
    run: |
      mkdir -p ~/.ssh
      chmod 700 ~/.ssh
      ssh-keyscan github.com >> ~/.ssh/known_hosts
      chmod 600 ~/.ssh/known_hosts

      ssh-agent -a "$RUNNER_TEMP/ssh_agent.sock" > "$RUNNER_TEMP/ssh_agent.env"
      source "$RUNNER_TEMP/ssh_agent.env"
      ssh-add - <<< "${{ secrets.SSH_PRIVATE_KEY }}"
      echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >> "$GITHUB_ENV"
      echo "SSH_AGENT_PID=$SSH_AGENT_PID" >> "$GITHUB_ENV"

  - uses: buildalon/unity-action@v3
    name: Project Validation
    with:
      log-name: project-validation
      build-target: ${{ matrix.build-target }}
      args: -quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject

  - name: Cleanup SSH auth for UPM git dependencies
    if: always()
    shell: bash
    run: |
      ssh-add -D || true
      if [ -n "${SSH_AGENT_PID:-}" ]; then
        kill "$SSH_AGENT_PID" || true
      fi

Git Submodules

Git submodules allow you to include and track external repositories within your main repository.

This works fine if the repository is public, but if it is private, you will need to generate a personal access token to access the repository. These are the same steps as above using either a personal access token or SSH key. Additionally, add the submodules: 'recursive' option to the actions/checkout step:

  uses: actions/checkout@v4
  with:
    token: ${{ secrets.CI_TOKEN }}
    submodules: 'recursive'

Unity Package Reference using a private scoped registry

Unity allows you to reference packages from a private scoped registry. This method is useful for including internal libraries or shared codebases.

You can access a private scoped registry using the upm-config action.

Next Steps

Triggers: Set up triggers to start workflows automatically.
Build Unity: Set up automated builds for your Unity project.
Buildalon Actions: Explore the actions available to use in your workflows.
Unit Testing: Automate unit testing to ensure stability and quality.
Deploy to Stores: Add deployment steps to distribute your app to users.
Dependencies: Learn what to do if your project depends on other private packages or repositories.