Using private Composer packages in your application

Using private Composer packages in your application

When your application uses private Composer packages from repositories like Private Packagist, GitHub, GitLab, or Bitbucket, you need to configure authentication during the build process. This guide explains how to set up Composer authentication using the platform's build commands and environment secrets features.

Understanding the build process

During deployment, your application's Docker image is built with the following process:

• Your repository is cloned using the connected Git account

• Build commands are executed in sequence during image construction

• Environment secrets are available as build arguments during the Docker build process only

• The final image is deployed to the platform

Important: Environment secrets are only available during the build process, not at application runtime. This means authentication tokens like COMPOSER_AUTH work for installing packages during the build but won't be present when your application runs.

Method 1: Using COMPOSER_AUTH environment variable (recommended)

This is the most secure and flexible method for authenticating with multiple package repositories.

Step 1: Create the authentication secret

1. Navigate to your application's settings

2. Scroll to the "Environment secrets" section

3. Add a new secret with key: COMPOSER_AUTH

4. Set the value to a JSON string containing your authentication details:

For Private Packagist:

{
  "http-basic": {
    "repo.packagist.com": {
      "username": "token",
      "password": "your-packagist-token"
    }
  }
}

For GitHub Packages:

{
  "github-oauth": {
    "github.com": "your-github-personal-access-token"
  }
}

For GitLab Packages:

{
  "gitlab-token": {
    "gitlab.com": "your-gitlab-token"
  }
}

For multiple repositories:

{
  "http-basic": {
    "repo.packagist.com": {
      "username": "token",
      "password": "your-packagist-token"
    }
  },
  "github-oauth": {
    "github.com": "your-github-token"
  }
}

Step 2: Configure build commands

1. In the settings, scroll to "Build commands"

2. Add the following command:

export COMPOSER_AUTH="$COMPOSER_AUTH" && composer install --no-dev --optimize-autoloader

The export command makes the authentication available to Composer, which will automatically use it when accessing private repositories.

Method 2: Using auth.json file

If you prefer to create an auth.json file during the build process:

Step 1: Create the authentication secret

Follow the same steps as Method 1 to create a COMPOSER_AUTH secret with your JSON authentication data.

Step 2: Configure build commands

Add these build commands in order:

echo "$COMPOSER_AUTH" > auth.json
composer install --no-dev --optimize-autoloader
rm -f auth.json

This creates the auth.json file, runs composer install, then removes the file for security.

Method 3: Repository-specific configuration

For authenticating with a single repository, you can use Composer's config commands:

Step 1: Create individual secrets

Add secrets for your specific repository:

• Key: PACKAGIST_TOKEN, Value: your-packagist-token

• Or Key: GITHUB_TOKEN, Value: your-github-token

Step 2: Configure build commands

For Private Packagist:

composer config http-basic.repo.packagist.com token "$PACKAGIST_TOKEN"
composer install --no-dev --optimize-autoloader

For GitHub:

composer config github-oauth.github.com "$GITHUB_TOKEN"
composer install --no-dev --optimize-autoloader

Best practices

• Use environment secrets: Never hardcode authentication tokens in build commands. Always use environment secrets to keep credentials secure.

• Token permissions: Create tokens with minimal required permissions (read-only access to packages).

• Token rotation: Regularly rotate your authentication tokens and update the secrets accordingly.

• Production optimization: Always use --no-dev and --optimize-autoloader flags for production builds.

• Redeploy after changes: Updating environment secrets requires redeployment to take effect.

Troubleshooting

Authentication failures

If you encounter authentication errors during build:

• Verify the JSON format in your COMPOSER_AUTH secret is valid

• Check that your token has the necessary permissions

• Ensure the repository URL in composer.json matches the authentication domain

Build command errors

If build commands fail:

• Check the deployment logs for specific error messages

• Verify that environment secrets are properly formatted (no extra quotes)

• Test your commands locally with the same authentication method

Security considerations

• Environment secrets are encrypted at rest in the database

• Secrets are only exposed during the build process as build arguments

• Build logs are automatically sanitized to prevent accidental exposure of secrets

• Each build runs in an isolated environment using separate containers

• Build processes run in isolated namespaces with automatic cleanup

Example: Laravel application with private packages

Here's a complete example for a Laravel application using private packages from Private Packagist:

Environment secrets:

• Key: COMPOSER_AUTH

• Value: {"http-basic":{"repo.packagist.com":{"username":"token","password":"your-token-here"}}}

Build commands:

1. export COMPOSER_AUTH="$COMPOSER_AUTH" && composer install --no-dev --optimize-autoloader

2. npm ci

3. npm run build

4. php artisan config:cache

5. php artisan route:cache

6. php artisan view:cache

This configuration ensures your private packages are accessible during the build while keeping your credentials secure.