From 9e88d62e1027b75d5a931565a96f2b8e876d31e6 Mon Sep 17 00:00:00 2001 From: Stephan Vock Date: Fri, 24 Jan 2025 11:21:54 +0000 Subject: [PATCH 1/4] Conductor: further explain setup steps --- docs/conductor/getting-started.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/conductor/getting-started.md b/docs/conductor/getting-started.md index 968aa7a6..7f0d2da8 100644 --- a/docs/conductor/getting-started.md +++ b/docs/conductor/getting-started.md @@ -1,25 +1,32 @@ # Getting started with Conductor ## -Conductor will group and schedule automated dependency updates on your own Continuous Integration platform. If the update succeeds, Conductor sends you a pull request to your code hosting platform (GitHub, GitLab, Bitbucket) with the changed composer.lock file and, if necessary, other files modified by Composer plugins or scripts. +Conductor will group and schedule automated dependency updates on your own Continuous Integration platform. If the update succeeds, Conductor will send you a pull request to your code hosting platform (GitHub, GitLab, Bitbucket) with the changed composer.lock file and, if necessary, other files modified by Composer plugins or scripts. To use Conductor: -- You need to be approved for early access to Conductor. [Join to the waitlist](/features/conductor) and wait for approval. +- You need to be approved for early access to Conductor. [Join the waitlist](/features/conductor) and wait for approval. - You need a Private Packagist trial or subscription on the cloud plan. -- You need to add a workflow to your Continuous Integration platform to run Composer updates, described below. +- You need to add a synchronization with your code hosting platform. +- You need to add a workflow to your Continuous Integration platform to run Composer updates. -## Add packages to update automatically +## Add a synchronization -Once you have a Private Packagist organization and Conductor is enabled for you, log into your Private Packagist organization and click on the "Updates" tab in the main navigation. +Once you have a Private Packagist organization and Conductor is enabled for you, log into your Private Packagist organization and head to the "Settings" tab in the main navigation. +Under the "Synchronization" entry you can add [one or more synchronizations](/features/integration-github-bitbucket-gitlab.md) with an organization on your code hosting platform. +This is how you grant us access to your repositories. Once done we will automatically add any repository with a composer.json file in the root directory as a package to Private Packagist. +## Configure Conductor for your packages + +Access the "Conductor" tab in the main navigation to see a list of available packages that can be managed via Conductor. +Each package shown is linked to a repository where you would like to receive pull requests from Conductor. This usually includes all your Composer projects. Conductor will manage dependencies for packages added to Private Packagist [via synchronization](/features/integration-github-bitbucket-gitlab.md) that have a composer.lock file committed to the repository. -## Create a workflow on your CI +To get started, click on the configure link displayed for the package where you want to use Conductor and follow the instructions for your Continuous Integration platform. ### GitHub Actions -Create a new GitHub Actions workflow in `.github/workflows/dependency-update.yaml` of your GitHub repository using the template below: +Create a new GitHub Actions workflow in `.github/workflows/conductor.yaml` of your GitHub repository using the template below: CONDUCTOR_GITHUB_ACTIONS_WORKFLOW @@ -31,13 +38,13 @@ We recommend to create a dedicated authentication token with update access. You ![Create Authentication Token](/Resources/public/img/docs/conductor/authentication-token.png) -The contents of the variable should look like +The contents of the variable should look like ```json {"http-basic": {"repo.packagist.com": {"username": "token", "password": "packagist_out_73a81c..." }}} ``` -Conductor needs to verify your CI setup before you can start receiving pull requests. +Conductor needs to verify your CI setup before you can start receiving PRs. ## Verify your CI setup @@ -58,7 +65,7 @@ When you run into errors, troubleshoot and fix them. You can trigger the workflo ## How scheduling works -- Navigate to the "Updates" tab in your Private Packagist organization +- Navigate to the "Conductor" tab in your Private Packagist organization - Click on the name of your package The list shows groups of all available updates to be scheduled. Each group of updates is called a task. Conductor will schedule only one task at a time. All others are waiting for the task on top of the list to be successful or paused. @@ -79,7 +86,7 @@ If all these steps succeeded, Private Packagist creates a pull request for the n ![Conductor Pull Request](https://packagist.com/img/features/auto-updates/merged-PR-for-a-security-updated.png) Once you reviewed the changes and merged the PR, Conductor will schedule the next task. -If you close the PR, the task will be paused and Conductor will schedule the next task. This is the same effect as using the "Pause" button in the UI. Conductor won't attempt to update the dependency to this exact version again but will schedule updates with newer versions. +If you close the PR, the task will be paused and Conductor will schedule the next task. This is the same effect as using the "Pause" button in the UI. Conductor won't attempt to update the dependency to this exact version again but will schedule updates with newer versions. If you want to schedule any other task in the list, click on its name and use the button "Schedule now to create a PR". From 028bf83d5bd8cf31ce84614c6e6b6fb3116daed1 Mon Sep 17 00:00:00 2001 From: Stephan Vock Date: Fri, 24 Jan 2025 11:52:03 +0000 Subject: [PATCH 2/4] Conductor: move steps to get to the task list --- docs/conductor/getting-started.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conductor/getting-started.md b/docs/conductor/getting-started.md index 7f0d2da8..e21c0358 100644 --- a/docs/conductor/getting-started.md +++ b/docs/conductor/getting-started.md @@ -48,6 +48,9 @@ Conductor needs to verify your CI setup before you can start receiving PRs. ## Verify your CI setup +- Navigate to the "Conductor" tab in your Private Packagist organization +- Click on the name of your package + ![Task list with verification task](/Resources/public/img/docs/conductor/verification-task-list.png) Right now all tasks are waiting for the CI verification task on top of the list. Conductor will not start with the regular schedule until this verification task was successful. @@ -65,9 +68,6 @@ When you run into errors, troubleshoot and fix them. You can trigger the workflo ## How scheduling works -- Navigate to the "Conductor" tab in your Private Packagist organization -- Click on the name of your package - The list shows groups of all available updates to be scheduled. Each group of updates is called a task. Conductor will schedule only one task at a time. All others are waiting for the task on top of the list to be successful or paused. Once Conductor schedules a task it sends a payload to your CI platform that triggers the workflow you just added. The payload contains the commands Composer will run to update a group of dependencies from your package. From a495f11c36bc77cf543a5b75c3401e333d1edf0e Mon Sep 17 00:00:00 2001 From: Stephan Vock Date: Fri, 24 Jan 2025 11:55:14 +0000 Subject: [PATCH 3/4] Conductor: reword repositories where one can receive PRs --- docs/conductor/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conductor/getting-started.md b/docs/conductor/getting-started.md index e21c0358..193ff667 100644 --- a/docs/conductor/getting-started.md +++ b/docs/conductor/getting-started.md @@ -19,7 +19,7 @@ This is how you grant us access to your repositories. Once done we will automati ## Configure Conductor for your packages Access the "Conductor" tab in the main navigation to see a list of available packages that can be managed via Conductor. -Each package shown is linked to a repository where you would like to receive pull requests from Conductor. This usually includes all your Composer projects. +Each package shown is linked to a repository where you can receive pull requests from Conductor. This usually includes all your Composer projects. Conductor will manage dependencies for packages added to Private Packagist [via synchronization](/features/integration-github-bitbucket-gitlab.md) that have a composer.lock file committed to the repository. To get started, click on the configure link displayed for the package where you want to use Conductor and follow the instructions for your Continuous Integration platform. From e8ac523894c6b0452dd73443ada72814b80d086d Mon Sep 17 00:00:00 2001 From: Stephan Date: Fri, 24 Jan 2025 13:12:19 +0000 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Nils Adermann --- docs/conductor/getting-started.md | 32 +++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/conductor/getting-started.md b/docs/conductor/getting-started.md index 193ff667..ac8e54e2 100644 --- a/docs/conductor/getting-started.md +++ b/docs/conductor/getting-started.md @@ -1,28 +1,28 @@ # Getting started with Conductor ## -Conductor will group and schedule automated dependency updates on your own Continuous Integration platform. If the update succeeds, Conductor will send you a pull request to your code hosting platform (GitHub, GitLab, Bitbucket) with the changed composer.lock file and, if necessary, other files modified by Composer plugins or scripts. +Conductor will group and schedule automated dependency updates on your own continuous integration platform. If the update succeeds, Conductor will send you a pull request to your code hosting platform (GitHub, GitLab, Bitbucket) with the changed composer.lock file and, if necessary, other files modified by Composer plugins or scripts. -To use Conductor: +Prerequisites for receiving dependency update PRs from Conductor: -- You need to be approved for early access to Conductor. [Join the waitlist](/features/conductor) and wait for approval. -- You need a Private Packagist trial or subscription on the cloud plan. -- You need to add a synchronization with your code hosting platform. -- You need to add a workflow to your Continuous Integration platform to run Composer updates. +- Receive early access to Conductor. [Join the waitlist](/features/conductor) and wait for approval. +- Set up an organization on Private Packagist Cloud either with a free trial or subscribe to the cloud plan. +- A synchronization in your Private Packagist organization with your code hosting platform. +- A workflow on your continuous integration platform to run Composer updates. -## Add a synchronization +## Set up synchronization Once you have a Private Packagist organization and Conductor is enabled for you, log into your Private Packagist organization and head to the "Settings" tab in the main navigation. Under the "Synchronization" entry you can add [one or more synchronizations](/features/integration-github-bitbucket-gitlab.md) with an organization on your code hosting platform. -This is how you grant us access to your repositories. Once done we will automatically add any repository with a composer.json file in the root directory as a package to Private Packagist. +This is how you grant us access to your VCS repositories. The synchronization will automatically add any repository with a composer.json file in the root directory as a package to Private Packagist. ## Configure Conductor for your packages -Access the "Conductor" tab in the main navigation to see a list of available packages that can be managed via Conductor. -Each package shown is linked to a repository where you can receive pull requests from Conductor. This usually includes all your Composer projects. -Conductor will manage dependencies for packages added to Private Packagist [via synchronization](/features/integration-github-bitbucket-gitlab.md) that have a composer.lock file committed to the repository. +Access the "Conductor" tab in the main navigation to see a list of available packages that can have their dependencies updated by Conductor. +Each package shown is linked to its VCS repository to which Conductor will send pull requests with dependency updates. Your Composer projects or applications are also a kind of package and must be added to Private Packagist as regular packages to use Conductor on them. +Conductor can only manage dependencies for packages added to Private Packagist [via synchronization](/features/integration-github-bitbucket-gitlab.md) that have a composer.lock file committed to the repository. -To get started, click on the configure link displayed for the package where you want to use Conductor and follow the instructions for your Continuous Integration platform. +To get started, click on the configure link displayed next to the package which you would like Conductor to update. Follow the instructions for your continuous integration platform. ### GitHub Actions @@ -38,7 +38,7 @@ We recommend to create a dedicated authentication token with update access. You ![Create Authentication Token](/Resources/public/img/docs/conductor/authentication-token.png) -The contents of the variable should look like +The contents of the variable should look like this: ```json {"http-basic": {"repo.packagist.com": {"username": "token", "password": "packagist_out_73a81c..." }}} @@ -48,8 +48,8 @@ Conductor needs to verify your CI setup before you can start receiving PRs. ## Verify your CI setup -- Navigate to the "Conductor" tab in your Private Packagist organization -- Click on the name of your package +- Navigate to the "Conductor" tab in your Private Packagist organization. +- Click on the name of your package. ![Task list with verification task](/Resources/public/img/docs/conductor/verification-task-list.png) @@ -86,7 +86,7 @@ If all these steps succeeded, Private Packagist creates a pull request for the n ![Conductor Pull Request](https://packagist.com/img/features/auto-updates/merged-PR-for-a-security-updated.png) Once you reviewed the changes and merged the PR, Conductor will schedule the next task. -If you close the PR, the task will be paused and Conductor will schedule the next task. This is the same effect as using the "Pause" button in the UI. Conductor won't attempt to update the dependency to this exact version again but will schedule updates with newer versions. +If you close the PR, the task will be paused and Conductor will schedule the next task. Clicking the "Pause" button in the UI has the same effect. Conductor won't attempt to update the dependency to this exact version again but it will schedule updates to newer versions. If you want to schedule any other task in the list, click on its name and use the button "Schedule now to create a PR".