Document first steps and how to setup github actions with Conductor #109
Conversation
|
Images automagically compressed by Calibre's image-actions ✨ Compression reduced images by 6.6%, saving 12.05 KB.
82 images did not require optimisation. |
| To use Conductor: | ||
|
|
||
| - You need to be approved for early access to conductor. [Join to the waitlist](http://packagist.com.lo/features/conductor) and wait for approval. | ||
| - You need a Private Packagist trial or subscription (Cloud or Self-Hosted). |
There was a problem hiding this comment.
Self-Hosted won't be supported until we have this somewhat stable/final.
|
|
||
| To use Conductor: | ||
|
|
||
| - You need to be approved for early access to conductor. [Join to the waitlist](http://packagist.com.lo/features/conductor) and wait for approval. |
There was a problem hiding this comment.
| - You need to be approved for early access to conductor. [Join to the waitlist](http://packagist.com.lo/features/conductor) and wait for approval. | |
| - You need to be approved for early access to Conductor. [Join to the waitlist](http://packagist.com.lo/features/conductor) and wait for approval. |
|
|
||
| ## First steps | ||
|
|
||
| Once you have a Private Packagist Subscription and Conductor is enabled for your subscription, log into your Private Packagist organization and click on the "Updates" tab in the main navigation. |
There was a problem hiding this comment.
This still mentions the need for a subscription. All they require is a Private Packagist organization.
| Conductor will list packages: | ||
| - added to Private Packagist via synchronization | ||
| - having a composer.lock file commited to the repository | ||
| - having the Private Packagist repository added to the composer.json |
There was a problem hiding this comment.
| Conductor will list packages: | |
| - added to Private Packagist via synchronization | |
| - having a composer.lock file commited to the repository | |
| - having the Private Packagist repository added to the composer.json | |
| Conductor will manage dependencies for packages added to Private Packagist via synchronization that have a composer.lock file committed to the repository. |
Looking at the list it isn't clear if a package needs to match one or all of the criteria. As we are already working on the third point, I would drop that already.
There was a problem hiding this comment.
Adding to Stephan's suggestion here, I would definitely make "via synchronization" a link to features/integration-github-bitbucket-gitlab, because if you're new to Private Packagist (or never used synchronization) it's not going to be clear enough.
|
|
||
| If you do not see your package, follow the instructions on your organization page to add the custom repository to the composer.json of your package. | ||
|
|
||
| Most convenient way to set up Conductor is to configure your CI in the Private Packagist UI. The manual steps are outlined below: |
There was a problem hiding this comment.
| Most convenient way to set up Conductor is to configure your CI in the Private Packagist UI. The manual steps are outlined below: | |
| The most convenient way to set up Conductor is to configure your CI in the Private Packagist UI. The manual steps are outlined below: |
This sounds a bit like Private Packagist provides functionality to configure the CI directly. All we do is list steps that they need to follow to set up CI.
There was a problem hiding this comment.
"The most convenient way" sounds to me as if there are other ways to set up Conductor too. There is no other path forward except adding the workflow to CI, right?
Because you also mention that CI workflow is a requirement in the introduction, I would even consider removing this line.
| 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, but will schedule updates with newer versions. | ||
|
|
||
| If you want to, schedule any other task of the list by clicking on its name and using the button "Schedule now to create a PR". |
There was a problem hiding this comment.
| If you want to, schedule any other task of the list by clicking on its name and using the button "Schedule now to create a PR". | |
| 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". |
|
|
||
| If you want to, schedule any other task of the list by clicking on its name and using the button "Schedule now to create a PR". | ||
|
|
||
| Tasks fixing security issues have a higher priority. They will be moved to the top of the list and scheduled right away. |
There was a problem hiding this comment.
| Tasks fixing security issues have a higher priority. They will be moved to the top of the list and scheduled right away. | |
| Tasks fixing security issues have a higher priority. They will be moved to the top of the list and scheduled right away even if there already is a PR for another task open. |
| {"http-basic": {"repo.packagist.com": {"username": "token", "password": "packagist_out_73a81c..." }}} | ||
| ``` | ||
|
|
||
| Conductor needs to verify your setup before you can [start receiving Pull Requests](#how-scheduling-works). |
There was a problem hiding this comment.
| Conductor needs to verify your setup before you can [start receiving Pull Requests](#how-scheduling-works). | |
| Conductor needs to [verify your CI setup](#verify-your-ci-setup) before you can start receiving pull requests. |
Thinking the important part here is that CI need to be verified.
| - Click on the task "Verify the continuous integration setup" | ||
| - Use the "Schedule now" button to test your setup | ||
|
|
||
| You can see the state of your task and last events for the task. Once the task is executed, watch your CI platform: |
There was a problem hiding this comment.
| You can see the state of your task and last events for the task. Once the task is executed, watch your CI platform: | |
| You can see the state of your task and the last events for the task. Once the task is executed, watch your CI platform: |
|
|
||
| If it was successful your CI configuration is verified and complete. Conductor will trigger your workflow with the next task in the list. This time it will send a pull request. | ||
|
|
||
| When you ran into errors, troubleshoot and fix. You can trigger the workflow again by restarting the CI verification task. The restart button is available after the first execution. |
There was a problem hiding this comment.
| When you ran into errors, troubleshoot and fix. You can trigger the workflow again by restarting the CI verification task. The restart button is available after the first execution. | |
| When you run into errors, troubleshoot and fix them. You can trigger the workflow again by restarting the CI verification task. The restart button is available after the first execution. |
|
Considering that I fully understand how all this works already. @stevenrombauts do you mind also taking a look at this? |
| - having a composer.lock file commited to the repository | ||
| - having the Private Packagist repository added to the composer.json | ||
|
|
||
| If you do not see your package, follow the instructions on your organization page to add the custom repository to the composer.json of your package. |
There was a problem hiding this comment.
This line can also be removed, then, since you're already working on removing the requirement of having the Private Packagist repository in composer.lock? (based on comments in earlier paragraph)
|
|
||
| If you do not see your package, follow the instructions on your organization page to add the custom repository to the composer.json of your package. | ||
|
|
||
| Most convenient way to set up Conductor is to configure your CI in the Private Packagist UI. The manual steps are outlined below: |
There was a problem hiding this comment.
"The most convenient way" sounds to me as if there are other ways to set up Conductor too. There is no other path forward except adding the workflow to CI, right?
Because you also mention that CI workflow is a requirement in the introduction, I would even consider removing this line.
| - You need a Private Packagist trial or subscription (Cloud or Self-Hosted). | ||
| - You need to add a workflow to your Continuous Integration platform to run Composer updates, described below. | ||
|
|
||
| ## First steps |
There was a problem hiding this comment.
| ## First steps | |
| ## Add packages to update automatically |
| 3. Review the steps to commit and push to your repository | ||
|
|
||
| Create a secret `COMPOSER_AUTH` with the Composer authentication configuration [as described here](https://getcomposer.org/doc/articles/authentication-for-private-packages.md#authentication-using-the-composer-auth-environment-variable) to access Private Packagist. | ||
| We recommend to create a dedicated authentication token with update access. You can copy and paste the contents for the secret from the Private Packagist UI while creating the token in "Settings" -> "Authentication Tokens". Remove the single quotes around the value. |
There was a problem hiding this comment.
| We recommend to create a dedicated authentication token with update access. You can copy and paste the contents for the secret from the Private Packagist UI while creating the token in "Settings" -> "Authentication Tokens". Remove the single quotes around the value. | |
| We recommend to create a dedicated authentication token with update access. You can copy and paste the contents for the secret from the "Environment variable" tab in the Private Packagist UI while creating the token in "Settings" -> "Authentication Tokens". Remove the single quotes around the value. |
Just to avoid confusion
| - Go to your package on the updates tab in your Private Packagist organization | ||
| - Click on the name of your package |
There was a problem hiding this comment.
Would also capitalize "Updates tab"
|
|
||
| Tasks fixing security issues have a higher priority. They will be moved to the top of the list and scheduled right away. | ||
|
|
||
| ## Verify your CI setup |
There was a problem hiding this comment.
I would move this before the "How scheduling works" section, because you need to verify anyway before you can do anything else, and you also don't want to cause confusion if there are no updates yet anyway?
| 6. Push commits to a new branch (or force push an existing branch) | ||
| 7. Send the status of the workflow to Private Packagist | ||
|
|
||
| If all these steps succeeded, Private Packagist creates a pull request for the just pushed branch. The PR description will contain details about the update and changelogs from your dependencies. Conductor integrates with [Update Review](https://packagist.com/features/update-review) to present a reviewable list of all updated dependencies. |
There was a problem hiding this comment.
| If all these steps succeeded, Private Packagist creates a pull request for the just pushed branch. The PR description will contain details about the update and changelogs from your dependencies. Conductor integrates with [Update Review](https://packagist.com/features/update-review) to present a reviewable list of all updated dependencies. | |
| If all these steps succeeded, Private Packagist creates a pull request for the newly pushed branch. The PR description will contain details about the update and changelogs from your dependencies. Conductor integrates with [Update Review](https://packagist.com/features/update-review) to present a reviewable list of all updated dependencies. |
| - Use the "Schedule now" button to test your setup | ||
|
|
||
| You can see the state of your task and last events for the task. Once the task is executed, watch your CI platform: | ||
| You should see a run for the just added workflow. Examine the run if it succeeded. |
There was a problem hiding this comment.
| You should see a run for the just added workflow. Examine the run if it succeeded. | |
| You should see a run for the just added workflow. Examine the run to see if it succeeded. |
Do you mean that you want the user to check it out regardless of the status, or really only take a look if it was successful?
No description provided.