README

The placetopay/app-version package provides a way to know which version of your app is currently deployed.

It can be used with Envoyer deployment hooks
It can be integrated with Sentry to help you keep track of Releases and Deploys in the Sentry Dashboard
Also you can integrate with NewRelic to track each deployment in your APM

Installation

Install using composer

composer require placetopay/app-version ^2.0

The package will automatically register itself and it should work now on your local environment

If you are using Sentry please follow this steps to configure the deployments and releases to your reports

Publish the configuration file

php artisan vendor:publish --provider="PlacetoPay\AppVersion\VersionServiceProvider"

Set up your environment variables at config/app-version.php

return [
    'sentry' => [
        /*
        * The sentry auth token used to authenticate with Sentry Api
        * Create tokens here at account level https://sentry.io/settings/account/api/auth-tokens/
        * Or here at organization level https://sentry.io/settings/your-organization/developer-settings/
        */
        'auth_token' => env('APP_VERSION_SENTRY_AUTH'),
        
        /*
        * The organization name this project belongs to, you can find out the
        * organization at https://sentry.io/settings/
        */
        'organization' => env('APP_VERSION_SENTRY_ORGANIZATION', 'placetopay'),
        
        /*
        * The repository name of this project. Repositories are added in sentry as integrations.
        * You must add your (Github|Bitbucket) integration at https://sentry.io/settings/your-organization/integrations/
        * and then add the repositories you want to track commits
        */
        'repository' => env('APP_VERSION_SENTRY_REPOSITORY'),
        
        /*
        * The name of this project in Sentry Dashboard
        * You can find out the project name at https://sentry.io/settings/your-organization/projects/
        */
        'project' => env('APP_VERSION_SENTRY_PROJECT'),
    ],
    'newrelic' => [
        /*
        * The NewRelic Rest API Key, you can found it on the following URL when you are logged in
        * https://rpm.newrelic.com/api/explore/application_deployments/create
        */
        'api_key' => env('APP_VERSION_NEWRELIC_API_KEY'),

        /*
         * The entityGuid value is the unique identifier assigned by New Relic to your system components during instrumentation and setup processes.
         * For more information on New Relic Entities and finding Entity GUIDs, see this guide.
         * https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#find
         */
        'entity_guid' => env('APP_VERSION_NEWRELIC_ENTITY_GUID'),

    ],
    'clickup' => [
        /*
         * The ClickUp API URL
        */
        'base_url' => env('CLICKUP_BASE_URL', 'https://api.clickup.com/api/v2'),

        /*
         * You can generate the ClickUp API token from the ClickUp settings at the following link:
         * https://app.clickup.com/settings/apps
        */
        'api_token' => env('CLICKUP_API_TOKEN'),
    ],

    /*
     * Name of the file that lists the changes made to the project
    */
    'changelog_file_name' => env('CHANGELOG_FILE', 'CHANGELOG.md'),
    /*
    * The current deployed version, will be read from version file
    * generated by `php artisan app-version:create ...` command
    */
    'version' => \PlacetoPay\AppVersion\VersionFile::read(),
    
    /*
     * The value of query param token to be able showed the deployed version.
     */
    'token' => env('APP_VERSION_TOKEN', 'delivery'),
];

Set up the config/sentry.php file with the following settings

return [
    'dsn' => env('SENTRY_LARAVEL_DSN', env('SENTRY_DSN')),

    // capture release as git sha
    'release' => \PlacetoPay\AppVersion\VersionFile::readSha(),

    'breadcrumbs' => [
        // Capture Laravel logs in breadcrumbs
        'logs' => true,

        // Capture SQL queries in breadcrumbs
        'sql_queries' => true,

        // Capture bindings on SQL queries logged in breadcrumbs
        'sql_bindings' => true,

        // Capture queue job information in breadcrumbs
        'queue_info' => true,
    ],

];

Usage

You can visit https://yourapp.com/version

Envoyer Hooks

Using tools to deploy like Envoyer there is no git source available once deployed so using the sha, project and branch available information we create a file containing this information

Create a deployment hook in the action "Activate New Release", it is vital that this hook runs BEFORE running config:cache or optimize commands

cd {{ release }}
php artisan app-version:create --sha={{ sha }} --time={{ time }} --project={{ project }} --branch={{ branch }}

This will generate your version file at storage/app/app-version.json

If you are integrating with Sentry or NewRelic Releases/Deployments/Issues, Add these hooks so Sentry and NewRelic can track your deployments. It should be run AFTER running the optimization or configuration cache.

cd {{ release }}
php artisan app-version:create-release
php artisan app-version:create-deploy

Know your version from CLI

If you're using tinker you can get the version information with the following commands

To access the version information generated with the step 1 of the usage

config('app-version.version.sha');

To access the sha

PlacetoPay\AppVersion\VersionFile::readSha()

ClickUp Integration

This package also provides a command to post comments on ClickUp tasks based on the changelog file. This is useful for tracking changes and updates in your projects.

Configuration

You need to make sure you have the clickup environment variables set in your config/app-version configuration file. You can see the variables to configure in step two of the installation process.
To generate clickup comments, you must run the command 'app-version:notify-clickup'.
```
php artisan app-version:notify-clickup
```
This command will read the changelog file specified in the configuration and post comments on ClickUp tasks that match the format specified in the changelog.

Note: The changelog file is specified in the config/app-version.php file under the changelog_file_name key. By default, it is set to CHANGELOG.md.
After this, your tasks will have a comment similar to the following:

Despliegue realizado en ambiente: develop Fecha: 2025-04-30 02:06:21 Versión: 3.1.0

Some of the supported formats for reading ClickUp tasks in the change log file are:

Versions:

1.0.0
[1.0.0]
1.0.0 (2024-01-01)
[1.0.0 (2024-01-01)]
[1.0.0 (2024-01-01)](https://bitbucket.org/project/commits/tag/6.1.15)

Tasks

Change [@user](https://bitbucket.org/user/) [#{CustomTaskId}](https://app.clickup.com/t/{TeamId}/{CustomTaskId})
Change [{CustomTaskId}](https://app.clickup.com/t/{TeamId}/{CustomTaskId})
Change (https://app.clickup.com/t/{TeamId}/{CustomTaskId}) 
Change [868c4frhp](https://app.clickup.com/t/{TaskId})

⚠️ Important: You must add the full URL of the corresponding ClickUp task, as this will retrieve both the task ID and team ID, which are necessary to generate the comment.

placetopay / app-version

Maintainers

Details