# Using private Composer packages in your application

> Install private Composer packages (Private Packagist, GitHub, GitLab, Bitbucket) by setting `COMPOSER_AUTH` as a build secret. Full JSON examples for each provider.

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:

```
{
  <span class="hljs-attr">"http-basic"</span>: {
    <span class="hljs-attr">"repo.packagist.com"</span>: {
      <span class="hljs-attr">"username"</span>: <span class="hljs-string">"token"</span>,
      <span class="hljs-attr">"password"</span>: <span class="hljs-string">"your-packagist-token"</span>
    }
  }
}
```

For GitHub Packages:

```
{
  <span class="hljs-attr">"github-oauth"</span>: {
    <span class="hljs-attr">"github.com"</span>: <span class="hljs-string">"your-github-personal-access-token"</span>
  }
}
```

For GitLab Packages:

```
{
  <span class="hljs-attr">"gitlab-token"</span>: {
    <span class="hljs-attr">"gitlab.com"</span>: <span class="hljs-string">"your-gitlab-token"</span>
  }
}
```

For multiple repositories:

```
{
  <span class="hljs-attr">"http-basic"</span>: {
    <span class="hljs-attr">"repo.packagist.com"</span>: {
      <span class="hljs-attr">"username"</span>: <span class="hljs-string">"token"</span>,
      <span class="hljs-attr">"password"</span>: <span class="hljs-string">"your-packagist-token"</span>
    }
  },
  <span class="hljs-attr">"github-oauth"</span>: {
    <span class="hljs-attr">"github.com"</span>: <span class="hljs-string">"your-github-token"</span>
  }
}
```

#### Step 2: Configure build commands

1. In the settings, scroll to "Build commands"
2. Add the following command:

```
<span class="hljs-keyword">export</span> COMPOSER_AUTH=<span class="hljs-string">"$COMPOSER_AUTH"</span> && 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:

```
<span class="hljs-keyword">echo</span> <span class="hljs-string">"$COMPOSER_AUTH"</span> > 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 <span class="hljs-string">"$PACKAGIST_TOKEN"</span>
composer install --no-dev --optimize-autoloader
```

For GitHub:

```
composer config github-oauth.github.com <span class="hljs-string">"$GITHUB_TOKEN"</span>
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.

## Frequently asked questions

### What is COMPOSER_AUTH and why is it needed?

COMPOSER_AUTH is an environment variable that Composer reads at build time to authenticate with private package registries. Use it to install packages from Private Packagist, private GitHub/GitLab/Bitbucket repos without baking credentials into your repository.

### How do I authenticate with private GitHub repositories in Composer?

Set COMPOSER_AUTH as a build secret with `{"github-oauth": {"github.com": "<your-personal-access-token>"}}`. The token needs `repo` scope to read private repositories.

### How do I authenticate with Private Packagist?

Set COMPOSER_AUTH to `{"http-basic": {"repo.packagist.com": {"username": "token", "password": "<your-packagist-token>"}}}`. Generate the token in your Private Packagist dashboard.

### Why isn't my COMPOSER_AUTH token available when my application runs?

COMPOSER_AUTH is intentionally a build-only secret on Ploi Cloud. It exists during the Docker build so Composer can install packages, but it is not injected into the runtime container. If you need the token at runtime, also add it as a runtime secret with a different variable name.

### How do I rotate Composer authentication tokens?

Generate a new token in your provider (GitHub, Private Packagist, etc.), update the COMPOSER_AUTH build secret in your application settings, then trigger a redeploy. The next build picks up the new token; the old one can be revoked safely after the build succeeds.