### ASUP Development Setup Example (.env)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/configuration.md

Presents an example .env file configuration for a development environment in ASUP. It highlights differences from production, such as enabling dry runs and aggressive updates.

```env
# General
SELF_TEST=1
DRY_RUN=1
VERBOSE=1

# Project
COMPOSER_UPDATE_CONSTRAINTS=1
APP_PUBLIC_ROOT_DIRECTORY=web

# VCS (GitHub)
VCS_PROVIDER=github
GIT_AUTO_MERGE=0
GIT_HOST=github.com
GIT_NAMESPACE=your-username
GIT_PROJECT=your-project
GIT_BRANCH_TARGET=develop
```

--------------------------------

### Configure ASUP Environment Variables

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/getting-started.md

Example configuration for the .env file used by ASUP. It includes general settings, project specifics, and version control system (VCS) parameters. Key variables like DRY_RUN and VCS_PROVIDER are shown.

```env
# General settings
SELF_TEST=1
DRY_RUN=1  # Set to 0 for production
VERBOSE=1

# Project settings
COMPOSER_UPDATE_CONSTRAINTS=0
APP_PUBLIC_ROOT_DIRECTORY=web

# VCS settings
VCS_PROVIDER="gitlab"  # or "github"
GIT_AUTO_MERGE=0
GIT_HOST="gitlab.example.com"
GIT_NAMESPACE="your-namespace"
GIT_PROJECT="your-project"
GIT_BRANCH_TARGET="main"
```

--------------------------------

### ASUP Basic Production Setup (.env)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/configuration.md

Provides a complete .env file configuration example for a basic production environment in ASUP. Includes general, project, VCS, authentication, and notification settings.

```env
# General
SELF_TEST=1
DRY_RUN=0
VERBOSE=1

# Project
COMPOSER_UPDATE_CONSTRAINTS=0
APP_PUBLIC_ROOT_DIRECTORY=web

# VCS (GitLab)
VCS_PROVIDER=gitlab
GIT_AUTO_MERGE=0
GIT_HOST=gitlab.example.com
GIT_NAMESPACE=your-org
GIT_PROJECT=your-project
GIT_BRANCH_TARGET=main

# Authentication
GIT_USER=your-username
GIT_TOKEN=your-token

# Notifications
MATTERMOST_HOOK=https://your-mattermost/hooks/your-webhook
```

--------------------------------

### Install and Run Markdownlint CLI

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/markdown-style-guide.md

Instructions for installing the markdownlint-cli globally and running it to check markdown files in a project.

```bash
npm install -g markdownlint-cli
markdownlint '**/*.md'
```

--------------------------------

### Display ASUP Public SSH Key

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/getting-started.md

Command to display the public SSH key generated by the ASUP setup script. This key is used to grant access to your Git provider.

```bash
cat ssh/id_asup.pub
```

--------------------------------

### Configure GitHub VCS Access

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/getting-started.md

Instructions and configuration snippet for setting up GitHub access for ASUP. Requires creating a Personal Access Token in GitHub and adding user and token details to the .env file.

```env
# VCS settings
GIT_USER="your-github-username"
GIT_TOKEN="your-github-token"
```

--------------------------------

### Example Markdown Links and Images

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/markdown-style-guide.md

Provides examples of correctly formatted markdown links and images, including alt text and optional titles for images.

```markdown
[Link text](https://example.com)
![Alt text](image.png "Optional title")
```

--------------------------------

### Configure Mattermost Webhook

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/getting-started.md

Configuration snippet for adding a Mattermost webhook URL to the .env file for notifications. This is an optional step.

```env
MATTERMOST_HOOK="https://your-mattermost-instance/hooks/your-webhook-id"
```

--------------------------------

### Setup Local ASUP Environment - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/index.md

This script sets up the local environment for ASUP. It requires Docker and Git to be installed.

```bash
./scripts/setup-local-env.sh
```

--------------------------------

### Example Markdown Headers

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/markdown-style-guide.md

Demonstrates the correct structure for markdown headers, ensuring they increment by one level at a time and use ATX style.

```markdown
# Top-level Header

## Second-level Header

### Third-level Header
```

--------------------------------

### Configure GitLab VCS Access

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/getting-started.md

Instructions and configuration snippet for setting up GitLab access for ASUP. Requires creating a Personal Access Token in GitLab and adding user and token details to the .env file.

```env
# VCS settings
GIT_USER="your-gitlab-username"
GIT_TOKEN="your-gitlab-token"
```

--------------------------------

### Example Markdown Lists

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/markdown-style-guide.md

Illustrates the proper formatting for unordered and ordered lists, including consistent indentation and numbering.

```markdown
- First item
- Second item
  - Nested item
  - Another nested item
- Third item

1. First ordered item
2. Second ordered item
   1. Nested ordered item
   2. Another nested item
3. Third ordered item
```

--------------------------------

### Integrate ASUP with GitHub Actions

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/getting-started.md

Configuration snippet for integrating ASUP into a GitHub Actions workflow. It uses the 'uses' keyword to reference the ASUP workflow file from a specific repository and branch.

```yaml
uses: your-org/asup/.github/workflows/ci.yml@main
```

--------------------------------

### Integrate ASUP with GitLab CI

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/getting-started.md

Configuration snippet for integrating ASUP into a GitLab CI/CD pipeline. It uses an include directive to import the ASUP's CI configuration from another project.

```yaml
include:
  - project: 'your-org/asup'
    file: '.gitlab-ci.yml'
```

--------------------------------

### Example Markdown Code Blocks (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/markdown-style-guide.md

Shows how to correctly format fenced code blocks in markdown, specifying the programming language.

```markdown
```php
echo "Hello, world!";
```
```

--------------------------------

### Example Markdown Emphasis

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/markdown-style-guide.md

Demonstrates the correct markdown syntax for emphasis (italics) using underscores and strong emphasis (bold) using asterisks.

```markdown
This is _emphasized_ text.
This is **strong** text.
```

--------------------------------

### Setup Local Environment for ASUP Updater

Source: https://github.com/aperta-be/asup-updater/blob/develop/CONTRIBUTING.md

This snippet shows the bash commands to clone the ASUP Updater repository, navigate into the directory, and set up the local development environment using a setup script. It's a prerequisite for local development.

```bash
git clone https://github.com/aperta-be/asup-updater.git
cd asup
./scripts/setup-local-env.sh
```

--------------------------------

### Compare Environment Files - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Compares the current environment file (`.env`) with an example file (`.env.example`) to identify missing or changed configuration settings. This is useful for diagnosing configuration problems. Requires Git or diff utility.

```bash
diff -u .env.example .env
```

--------------------------------

### GitLab VCS Provider Implementation Example (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

An example implementation of the VcsProviderInterface for GitLab, demonstrating how to structure a concrete VCS provider. It includes a placeholder for the authenticate method.

```php
use Asup\VCS\VcsProviderInterface;

class GitLabProvider implements VcsProviderInterface
{
    public function authenticate(): bool
    {
        // Implementation
    }
    
    // Other method implementations...
}
```

--------------------------------

### PHP Test Environment Setup and Cleanup

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

This snippet demonstrates how to use the TestHelper class in PHP to create a test environment and clean it up afterwards. It requires the AsupTestingTestHelper namespace.

```php
use Asup\Testing\TestHelper;

// Create test environment
TestHelper::createTestEnv();

// Clean up
TestHelper::cleanup();
```

--------------------------------

### ASUP Configuration Response (JSON)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Example JSON response for the GET /api/config endpoint, showing configuration settings such as the chosen VCS provider, update strategy, notification methods, and auto-merge status.

```json
{
    "vcsProvider": "gitlab",
    "updateStrategy": "conservative",
    "notifications": ["mattermost"],
    "autoMerge": false
}
```

--------------------------------

### Manual Git Merge and Conflict Resolution - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Guides through the manual process of merging a target branch into the current branch and resolving any resulting merge conflicts. This is essential when automatic updates fail due to conflicting changes. Requires Git to be installed.

```bash
git checkout update-branch
git merge target-branch
# Resolve conflicts
git commit
```

--------------------------------

### ASUP API Versioning Example (HTTP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Illustrates how ASUP versioning is handled via the URL path. Both '/api/v1/status' and '/api/v2/status' are shown as examples of accessing different API versions.

```http
/api/v1/status
/api/v2/status
```

--------------------------------

### Update ASUP using Git and Build Script

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

This snippet demonstrates how to update the ASUP software by pulling the latest changes from the repository and then executing a local build script. Ensure you have Git installed and the build script is executable.

```bash
# Update ASUP
git pull
./build.local.sh
```

--------------------------------

### Reset Git Branch to Remote - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Resets the current local branch to match the state of a specified remote branch, discarding all local changes. This is used to recover from failed updates or merge conflicts by starting fresh from the remote state. Requires Git to be installed.

```bash
git reset --hard origin/main
# Re-run ASUP
```

--------------------------------

### ASUP Status Response (JSON)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Example JSON response for the GET /api/status endpoint, detailing the service's status, version, the timestamp of the last update, and the count of pending updates.

```json
{
    "status": "active",
    "version": "1.0.0",
    "lastUpdate": "2025-04-14T12:00:00Z",
    "pendingUpdates": 0
}
```

--------------------------------

### GitHub Actions Configuration for ASUP

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/configuration.md

Demonstrates how to configure ASUP settings in GitHub Actions using environment variables, including Git token and Mattermost webhook.

```yaml
env:
  GIT_TOKEN: ${{ secrets.GIT_TOKEN }}
  MATTERMOST_HOOK: ${{ secrets.MATTERMOST_HOOK }}
```

--------------------------------

### ASUP Incoming Webhook Example (HTTP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Example of an incoming webhook payload received by ASUP, likely from a VCS system like GitHub. This POST request contains information about a code push event, including the repository and branch.

```http
POST /webhook/github
Content-Type: application/json

{
    "ref": "refs/heads/main",
    "repository": {
        "full_name": "org/repo"
    }
}
```

--------------------------------

### View Docker Container Logs - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Retrieves the logs from a running Docker container. This is essential for diagnosing runtime issues, crashes, or unexpected behavior within a container. Requires Docker to be installed and the container ID.

```bash
docker logs container_id
```

--------------------------------

### Validate Composer Configuration - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Validates the syntax and structure of the `composer.json` file. This command helps identify issues with dependency definitions or version constraints, preventing Composer update failures. Requires Composer to be installed.

```bash
composer validate
```

--------------------------------

### Check Docker Daemon Information - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Displays information about the Docker daemon, including version, storage driver, and system resources. This command is used to diagnose issues related to the Docker environment itself. Requires Docker to be installed.

```bash
docker info
docker system df
```

--------------------------------

### Enable Composer Parallel Downloads - Env

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Configures Composer to use parallel downloads for packages, potentially speeding up update processes. This can help mitigate performance issues related to slow updates. Requires Composer to be installed.

```env
COMPOSER_PARALLEL_DOWNLOADS=4
```

--------------------------------

### Test SSL/TLS Connection - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Tests the SSL/TLS connection to a server on a specified port using OpenSSL. This command is useful for diagnosing SSL/TLS certificate errors and handshake failures. Requires OpenSSL to be installed.

```bash
openssl s_client -connect gitlab.example.com:443
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/aperta-be/asup-updater/blob/develop/README.md

Copies an example environment file to be used for actual configuration. Users should edit the copied '.env' file with their specific settings.

```bash
cp .env.example .env
```

--------------------------------

### Configure ASUP Updater Local Environment

Source: https://github.com/aperta-be/asup-updater/blob/develop/CONTRIBUTING.md

This snippet demonstrates how to copy the example environment file and then edit the .env file to configure the ASUP Updater for local development. This step is crucial for setting up database credentials, API keys, and other environment-specific settings.

```bash
cp .env.example .env
# Edit .env with your settings
```

--------------------------------

### ASUP Event Listener Example (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Demonstrates how to register an event listener in ASUP using the `on` method. This example shows attaching a callback function to the 'pre.update' event to handle actions before an update is applied.

```php
$asup->on('pre.update', function($event) {
    // Handle pre-update event
});
```

--------------------------------

### Configure ASUP Environment - Shell

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/index.md

This command opens the .env file in the nano editor for configuring ASUP settings. Ensure you have nano installed or use your preferred editor.

```bash
nano .env
```

--------------------------------

### GitLab CI Configuration for ASUP

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/configuration.md

Illustrates setting up ASUP configuration within GitLab CI pipeline variables. It specifies git strategy, depth, and composer update constraints.

```yaml
variables:
  GIT_STRATEGY: clone
  GIT_DEPTH: 0
  COMPOSER_UPDATE_CONSTRAINTS: 1
```

--------------------------------

### Mattermost Notifier Usage Example (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Demonstrates the usage of a Mattermost notifier, showing how to instantiate the notifier with a webhook URL and send a notification message. Assumes a MattermostNotifier class implementing NotificationProviderInterface.

```php
$notifier = new MattermostNotifier($webhookUrl);
$notifier->send('Update completed successfully');
```

--------------------------------

### Clone ASUP Repository - Git

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/index.md

This command clones the ASUP repository from GitHub. It requires Git to be installed on your system.

```bash
git clone https://github.com/your-org/asup.git
cd asup
```

--------------------------------

### ASUP Advanced Configuration: Update Strategies (.env)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/configuration.md

Demonstrates setting update strategies in ASUP's .env file. Options include conservative (recommended for production) and aggressive updates, controlling composer.json constraint updates and automatic branch merging.

```env
# Conservative updates (recommended for production)
COMPOSER_UPDATE_CONSTRAINTS=0
GIT_AUTO_MERGE=0

# Aggressive updates (use with caution)
COMPOSER_UPDATE_CONSTRAINTS=1
GIT_AUTO_MERGE=1
```

--------------------------------

### Monitor Docker Container Resource Usage - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Displays real-time resource usage (CPU, memory, network I/O, block I/O) for a Docker container. This helps diagnose performance issues and resource limitations within containers. Requires Docker to be installed and the container ID.

```bash
docker stats container_id
```

--------------------------------

### Run ASUP Docker Container - Docker CLI

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/index.md

This command runs the ASUP Docker container using the configuration from the .env file. Docker must be installed and running.

```bash
docker run --env-file .env your-org/asup:latest
```

--------------------------------

### Monitor Docker Disk Space

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

This command checks the disk space usage by Docker. It helps in identifying potential storage issues related to Docker images, containers, and volumes. This command requires Docker to be installed and running.

```bash
docker system df
```

--------------------------------

### Test Git Provider Connectivity with cURL - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Tests network connectivity and SSL/TLS handshake with a Git provider using cURL. The verbose flag (-v) provides detailed information about the connection process, useful for diagnosing network and SSL errors. Requires cURL to be installed.

```bash
curl -v https://gitlab.example.com
```

--------------------------------

### Conservative Update Strategy Implementation (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

An example implementation of the UpdateStrategyInterface named 'ConservativeStrategy'. It includes a placeholder for the analyze method and implies other methods would be implemented for a complete strategy.

```php
class ConservativeStrategy implements UpdateStrategyInterface
{
    public function analyze(): array
    {
        // Implementation
    }
    
    // Other method implementations...
}
```

--------------------------------

### Set PHP Memory Limit - Env

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Sets the memory limit for PHP processes. Increasing this limit can resolve 'memory limit errors' during Composer updates or other PHP-intensive operations. Requires Composer and PHP to be installed.

```env
PHP_MEMORY_LIMIT=2G
```

--------------------------------

### Configure Composer Cache Directory - Env

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Specifies a custom directory for Composer's cache. Using a dedicated cache directory, potentially on faster storage or a shared volume, can improve update performance. Requires Composer to be installed.

```env
COMPOSER_CACHE_DIR=/cache
```

--------------------------------

### Verify DNS Resolution - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Verifies DNS resolution for a given hostname using `nslookup` or `dig`. This helps diagnose network issues related to incorrect or unavailable DNS records. Requires `nslookup` or `dig` to be installed.

```bash
nslookup gitlab.example.com
dig gitlab.example.com
```

--------------------------------

### ASUP Advanced Configuration: Custom SSH Keys (.env)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/configuration.md

Shows how to configure custom SSH keys for ASUP by providing paths to public and private SSH key files within the .env configuration.

```env
# Use custom SSH keys
SSH_PUBLIC_KEY="ssh-ed25519 AAAAC3..."
SSH_PRIVATE_KEY="-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----"
```

--------------------------------

### Clean Docker System - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Prunes unused Docker data (images, containers, networks, volumes) to free up disk space and resolve potential issues caused by stale Docker resources. This is a common step before rebuilding or running containers. Requires Docker to be installed.

```bash
docker system prune -a
./build.local.sh
```

--------------------------------

### ASUP CLI Configuration Command (Bash)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Command to configure ASUP settings via the CLI. This example shows how to set the 'autoMerge' option to 'true'.

```bash
asup config set autoMerge true
```

--------------------------------

### Test SSH Connection - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Tests the SSH connection to a Git provider to diagnose 'Permission denied (publickey)' errors. This command verifies if SSH keys are correctly configured and authorized. It requires SSH access to the specified Git provider.

```bash
ssh -T git@github.com  # For GitHub
ssh -T git@gitlab.com  # For GitLab
```

--------------------------------

### Clear Composer Cache - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Clears the Composer cache, which can resolve issues caused by corrupted or outdated cached packages. This is a useful step when encountering dependency conflicts or update failures. Requires Composer to be installed.

```bash
composer clear-cache
```

--------------------------------

### Monitor File System Disk Space

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

This command displays the amount of disk space used and available on the file system in a human-readable format. It is useful for general system monitoring beyond Docker. Requires standard Unix/Linux command-line access.

```bash
df -h
```

--------------------------------

### Prune Unused Docker Data

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

This command removes unused Docker objects, including stopped containers, dangling images, and unused networks and volumes. Use with caution as it can remove data that might be needed later. Requires Docker to be installed and running.

```bash
docker system prune
```

--------------------------------

### ASUP Rate Limiting Headers (HTTP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Example HTTP response headers related to API rate limiting. These headers indicate the total limit, remaining requests, and the time (Unix timestamp) when the limit resets.

```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1618408800
```

--------------------------------

### Enable Debug Mode - Env

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Sets environment variables to enable verbose logging and debug mode. This increases the level of detail in application logs, aiding in the diagnosis of complex issues. Requires the application to respect these environment variables.

```env
VERBOSE=1
DEBUG=1
```

--------------------------------

### ASUP Token Authentication Header (HTTP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Example of an HTTP Authorization header using Bearer token authentication, which is a common method for securing API endpoints in ASUP.

```http
Authorization: Bearer <token>
```

--------------------------------

### View Application Logs from Container - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Executes a command inside a Docker container to read the application log file. This is useful for inspecting application-specific errors that may not be captured by Docker logs. Requires Docker and the container ID.

```bash
docker exec container_id cat /var/log/asup.log
```

--------------------------------

### Verify Git Provider Authentication Token - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Verifies the scopes of a Git provider authentication token by making a request to the provider's API. This is useful for diagnosing 'Authentication failed' errors. It requires a valid token and the API endpoint for the Git provider.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
    https://api.github.com/user  # For GitHub
```

--------------------------------

### Configure Proxy Environment Variables - Env

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Sets environment variables for HTTP and HTTPS proxy configurations. This is used to enable network traffic to go through a proxy server, resolving connectivity issues in restricted network environments. Requires knowledge of the proxy server address and port.

```env
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1
```

--------------------------------

### Test Mattermost Webhook - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Sends a test message to a Mattermost channel via a webhook URL. This is used to verify integration issues with Mattermost notifications. Requires a valid Mattermost webhook URL and cURL.

```bash
curl -X POST -H "Content-Type: application/json" \
    -d '{"text":"Test message"}' \
    $MATTERMOST_HOOK
```

--------------------------------

### Ping Git Provider - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Checks network connectivity to a Git provider by sending ICMP echo requests. This is used to diagnose network issues like connection timeouts. It requires network access to the target host.

```bash
ping gitlab.example.com
```

--------------------------------

### Check File Permissions - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Lists file and directory permissions in long format (`ls -la`). This helps diagnose configuration or integration issues related to incorrect file or directory access rights. Requires shell access to the file system.

```bash
ls -la .env
ls -la ssh/
```

--------------------------------

### ASUP Configuration HTTP Endpoint (HTTP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines the GET request for the /api/config endpoint, used to retrieve the current ASUP configuration. Requires Bearer token authentication and returns configuration details like VCS provider, update strategy, and notifications.

```http
GET /api/config
Authorization: Bearer <token>
```

--------------------------------

### ASUP Status HTTP Endpoint (HTTP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines the GET request for the /api/status endpoint, which provides information about the ASUP service's current operational state, version, last update time, and pending updates.

```http
GET /api/status
```

--------------------------------

### Check Git Provider API Rate Limits - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Retrieves the current API rate limit status for a Git provider (e.g., GitHub). This helps diagnose issues related to exceeding API usage limits, which can cause integration failures. Requires a valid API token and cURL.

```bash
# For GitHub
curl -H "Authorization: Bearer $GIT_TOKEN" \
    https://api.github.com/rate_limit
```

--------------------------------

### Set SSH Key Permissions - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Sets the correct file permissions for SSH private and public keys. Proper permissions (600 for private, 644 for public) are crucial for SSH security and functionality. This command is used to fix permission errors.

```bash
chmod 600 ssh/id_asup
chmod 644 ssh/id_asup.pub
```

--------------------------------

### Check Git Token Environment Variable - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Checks if the Git token environment variable is set by counting its characters. A value greater than 1 indicates the token is present. This helps in diagnosing authentication issues related to missing or empty tokens.

```bash
echo $GIT_TOKEN | wc -c  # Should be > 1
```

--------------------------------

### Add SSH Key to Agent - Bash

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/troubleshooting.md

Adds an SSH private key to the SSH agent, allowing it to be used for authentication without re-entering the passphrase. This is a common step for resolving SSH connection issues. It requires the SSH agent to be running.

```bash
eval "$(ssh-agent -s)"
ssh-add ssh/id_asup
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/aperta-be/asup-updater/blob/develop/README.md

Clones the ASUP repository and changes the current directory into it. This is the initial step for setting up the project locally.

```bash
git clone https://github.com/aperta-be/asup-updater.git
cd asup
```

--------------------------------

### ASUP Testing Mock Classes (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

PHP code demonstrating the use of mock classes for testing ASUP integrations. It shows how to instantiate ASUP with mock providers for VCS and notifications, allowing for isolated unit tests.

```php
use Asup\Testing\MockVcsProvider;
use Asup\Testing\MockNotifier;

// Use in tests
$asup = new Asup(new MockVcsProvider());
```

--------------------------------

### API Versioning

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Illustrates how ASUP API versions are handled through URL paths.

```APIDOC
## API Versioning

### Description
The ASUP API is versioned through the URL path to allow for future compatibility and evolution.

### Endpoint Examples
- `/api/v1/status`
- `/api/v2/status`

### Current Stable Version
v1
```

--------------------------------

### Build and Test ASUP Updater Locally

Source: https://github.com/aperta-be/asup-updater/blob/develop/CONTRIBUTING.md

These bash commands are used to build the ASUP Updater locally and run its test suite. The build script compiles assets or prepares the application, while the test script ensures the code functions as expected and meets quality standards.

```bash
./build.local.sh
./test.sh
```

--------------------------------

### Run Tests

Source: https://github.com/aperta-be/asup-updater/blob/develop/README.md

Executes the test suite for the ASUP project. This is a crucial step for verifying the integrity and functionality of the codebase during development.

```bash
./test.sh
```

--------------------------------

### Configuration Endpoint

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Retrieves the current ASUP configuration, including VCS provider, update strategy, and notification settings.

```APIDOC
## GET /api/config

### Description
Retrieves the current ASUP configuration, including VCS provider, update strategy, and notification settings.

### Method
GET

### Endpoint
/api/config

### Parameters
#### Query Parameters
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **vcsProvider** (string) - The configured VCS provider (e.g., "gitlab").
- **updateStrategy** (string) - The configured update strategy (e.g., "conservative").
- **notifications** (array of strings) - A list of configured notification providers (e.g., ["mattermost"]).
- **autoMerge** (boolean) - Whether auto-merge is enabled.

#### Response Example
```json
{
    "vcsProvider": "gitlab",
    "updateStrategy": "conservative",
    "notifications": ["mattermost"],
    "autoMerge": false
}
```
```

--------------------------------

### VCS Provider Interface Definition (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines the contract for Version Control System (VCS) providers, outlining methods for authentication, repository cloning, branch creation, pushing changes, creating merge requests, and auto-merging.

```php
interface VcsProviderInterface
{
    public function authenticate(): bool;
    public function cloneRepository(): bool;
    public function createBranch(string $name): bool;
    public function pushChanges(): bool;
    public function createMergeRequest(array $options): array;
    public function autoMerge(int $requestId): bool;
}
```

--------------------------------

### Run Quality Checks for ASUP Updater

Source: https://github.com/aperta-be/asup-updater/blob/develop/CONTRIBUTING.md

This snippet includes bash commands to perform static code analysis and run tests for the ASUP Updater project. It utilizes `phpcs` for code style checks and `phpstan` for type checking, along with the project's test script to ensure code quality before submitting changes.

```bash
vendor/bin/phpcs --standard=phpcs.xml
vendor/bin/phpstan analyse
./test.sh
```

--------------------------------

### Generate SSH Keys

Source: https://github.com/aperta-be/asup-updater/blob/develop/README.md

Generates SSH keys for project access, likely used for interacting with version control systems. The 'your-project' argument specifies the project name for key generation.

```bash
./scripts/generate-ssh-keys.sh your-project
```

--------------------------------

### Token Authentication

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Details how to authenticate API requests using Bearer tokens.

```APIDOC
## Token Authentication

### Description
API requests can be authenticated using a Bearer token.

### Method
Header

### Parameter
- **Authorization** (string) - Required - The authentication token in the format `Bearer <token>`.
```

--------------------------------

### Register SSH Key for Authentication (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

PHP code snippet showing how to register an SSH key with ASUP, likely for authenticating with Git repositories. It uses the `registerSshKey` method with the path to the private key file.

```php
// Register SSH key
Asup::registerSshKey('/path/to/key');
```

--------------------------------

### Register Custom VCS Provider (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Code snippet showing how to register a custom VCS provider with ASUP. It uses the `registerVcsProvider` static method, associating a name with the custom provider class.

```php
// Register custom VCS provider
Asup::registerVcsProvider('custom', CustomVcsProvider::class);

// Use in configuration
VCS_PROVIDER=custom
```

--------------------------------

### Container Structure - File System

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/architecture.md

Illustrates the file system layout within the ASUP Docker container, showing directories for code, mounted volumes (like SSH keys), and entry points.

```plaintext
/
├── code/
│   ├── project/          # Cloned repository
│   ├── app/
│   │   ├── php/         # PHP integration scripts
│   │   └── sh/          # Shell scripts
│   └── api/             # API libraries
├── mount/
│   └── ssh/             # SSH keys
└── usr/local/bin/       # Entry points
```

--------------------------------

### Extensibility - Plugin Architecture

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/architecture.md

Defines the directory structure for ASUP's plugin architecture, categorizing plugins by their functionality such as VCS providers, notification systems, and update validators.

```plaintext
plugins/
├── vcs/              # VCS provider plugins
├── notifications/    # Notification plugins
└── validators/       # Update validators
```

--------------------------------

### Update Strategy Interface Definition (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines the contract for update strategies, outlining methods for analyzing the current state, planning updates, applying updates, and validating the update process. This enables custom update logic.

```php
interface UpdateStrategyInterface
{
    public function analyze(): array;
    public function planUpdates(): array;
    public function applyUpdates(): bool;
    public function validate(): bool;
}
```

--------------------------------

### Notification Provider Interface Definition (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines the contract for notification providers, specifying methods for sending messages, formatting message data, and validating configuration settings. This allows for pluggable notification systems.

```php
interface NotificationProviderInterface
{
    public function send(string $message): bool;
    public function formatMessage(array $data): string;
    public function validateConfig(): bool;
}
```

--------------------------------

### Register Custom Notifier (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Code snippet demonstrating how to register a custom notifier with ASUP. It uses the `registerNotifier` static method to link a name (e.g., 'slack') to a custom notifier class.

```php
// Register custom notifier
Asup::registerNotifier('slack', SlackNotifier::class);

// Use in configuration
NOTIFICATION_PROVIDER=slack
```

--------------------------------

### Register Custom Update Strategy (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Code snippet illustrating how to register a custom update strategy with ASUP. The `registerStrategy` method associates a name (e.g., 'careful') with a custom strategy class.

```php
// Register custom strategy
Asup::registerStrategy('careful', CarefulStrategy::class);

// Use in configuration
UPDATE_STRATEGY=careful
```

--------------------------------

### Development - Code Organization

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/architecture.md

Outlines the source code directory structure for ASUP, organizing code by core functionality, integrations (VCS, Composer), notification systems, and utility functions.

```plaintext
src/
├── Core/            # Core functionality
├── VCS/            # VCS integrations
├── Composer/       # Composer operations
├── Notification/   # Notification system
└── Utils/          # Utility functions
```

--------------------------------

### ASUP CLI Trigger Update Command (Bash)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Command to trigger an update for a specified repository and branch using the ASUP CLI. It allows specifying the repository and branch as arguments.

```bash
asup update --repo=org/repo --branch=main
```

--------------------------------

### ASUP Outgoing Webhook Registration (PHP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Code snippet demonstrating how to register an outgoing webhook in ASUP. It specifies the URL to send notifications to, the events to trigger the webhook, and a secret for message verification.

```php
// Register webhook
Asup::registerWebhook('https://api.example.com/webhook', [
    'events' => ['update.complete', 'error'],
    'secret' => 'webhook-secret'
]);
```

--------------------------------

### ASUP Available Events (PHP Constants)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines a list of available event names within the ASUP system, used for hooking into various stages of the update process. These constants represent triggers for event listeners.

```php
const EVENTS = [
    'pre.update',
    'post.update',
    'pre.merge',
    'post.merge',
    'error',
    'notification'
];
```

--------------------------------

### Incoming Webhook

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Receives webhook notifications from external services, such as Git events, to trigger actions within ASUP.

```APIDOC
## POST /webhook/github

### Description
Receives webhook notifications from external services, such as Git events, to trigger actions within ASUP.

### Method
POST

### Endpoint
/webhook/github

### Parameters
#### Request Body
- **ref** (string) - Required - The reference that was updated (e.g., "refs/heads/main").
- **repository** (object) - Required - Information about the repository.
  - **full_name** (string) - Required - The full name of the repository (e.g., "org/repo").

### Request Example
```json
{
    "ref": "refs/heads/main",
    "repository": {
        "full_name": "org/repo"
    }
}
```
```

--------------------------------

### ASUP CLI Status Command (Bash)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Command to check the current status of the ASUP service using its command-line interface. This is a basic diagnostic command.

```bash
asup status
```

--------------------------------

### ASUP Trigger Update HTTP Endpoint (HTTP)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines the POST request for the /api/trigger endpoint, used to initiate an update process. It requires a JSON payload specifying the repository, branch, and optional update parameters like auto-merge.

```http
POST /api/trigger
Content-Type: application/json

{
    "repository": "org/repo",
    "branch": "main",
    "options": {
        "autoMerge": true
    }
}
```

--------------------------------

### Status Endpoint

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Retrieves the current status of the ASUP service, including version, last update time, and pending updates.

```APIDOC
## GET /api/status

### Description
Retrieves the current status of the ASUP service, including version, last update time, and pending updates.

### Method
GET

### Endpoint
/api/status

### Response
#### Success Response (200)
- **status** (string) - The current status of the service (e.g., "active").
- **version** (string) - The current version of ASUP.
- **lastUpdate** (string) - The timestamp of the last update.
- **pendingUpdates** (integer) - The number of pending updates.

#### Response Example
```json
{
    "status": "active",
    "version": "1.0.0",
    "lastUpdate": "2025-04-14T12:00:00Z",
    "pendingUpdates": 0
}
```
```

--------------------------------

### Generate Debug Report

Source: https://github.com/aperta-be/asup-updater/blob/develop/README.md

Generates a debug report for the ASUP project. This script is likely used for diagnosing issues or collecting information for bug reporting.

```bash
./scripts/debug-report.sh
```

--------------------------------

### ASUP Error Response Format (JSON)

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Defines the standard JSON structure for error responses from ASUP. It includes an error code, a human-readable message, and optional detailed information about the error.

```json
{
    "error": {
        "code": 1000,
        "message": "Authentication failed",
        "details": {
            "provider": "gitlab",
            "reason": "Invalid token"
        }
    }
}
```

--------------------------------

### Trigger Update Endpoint

Source: https://github.com/aperta-be/asup-updater/blob/develop/docs/api.md

Triggers an update process for a specified repository and branch, with optional settings like auto-merge.

```APIDOC
## POST /api/trigger

### Description
Triggers an update process for a specified repository and branch, with optional settings like auto-merge.

### Method
POST

### Endpoint
/api/trigger

### Parameters
#### Request Body
- **repository** (string) - Required - The repository to update (e.g., "org/repo").
- **branch** (string) - Required - The branch to update (e.g., "main").
- **options** (object) - Optional - Additional options for the update process.
  - **autoMerge** (boolean) - Optional - Whether to automatically merge changes.

### Request Example
```json
{
    "repository": "org/repo",
    "branch": "main",
    "options": {
        "autoMerge": true
    }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.