CI/CD
Last updated
Last updated
OnePub is simple to integrate into your CI/CD framework.
In most CI/CD environments there is no user interaction, so it's not possible to run 'onepub login'.
To overcome this limitation OnePub provides the ability to authenticate to OnePub (from the CLI) using a OnePub token.
To use a OnePub token in your CI/CD environment you need to first 'export' a OnePub token and then import it into your CI/CD environment.
To move forward you will need:
You will need the OnePub CLI tools installed into your CI/CD environment.
A OnePub token with the requisite privileges.
Modifications to your test scripts (e.g. GitHub Actions) to import a OnePub Token
The following describes the process for setting up your CI/CD environment.
OnePub recommends that you create a dedicated CI/CD member account. The CI/CD Member will be used from your CI/CD environment to authenticate to OnePub from your test scripts (e.g. GitHub actions).
To create a CI/CD member account:
1) log into the OnePub web interface.
2) Open the Members View.
3) Open the context menu and select 'Create CI/CD User'.
4) Enter a name for the CI/CD user. The name might be derived from the name of the CI/CD server it will run on, just choose something meaningful to your team.
A OnePub Administrator can export any other Member's OnePub Token. A OnePub Team Leader can export any of their team's OnePub Tokens.
Within OnePub, a OnePub Token is always tied to a member and that member's permissions.
When deploying a OnePub Token to your CI/CD environment you need to ensure that the member associated with the OnePub Token has sufficient permissions for the actions the CI/CD will take.
When you created the above CI/CD member they will have been added to the 'EveryOne' Team. This gives them access to every package associated with the EveryOne team. You may want to change the Team(s) the CI/CD member is associated with to restrict what packages they have access to.
To use a OnePub CI/CD Member account you need to import the member's OnePub token into the CI/CD environment.
To do this you must first obtain a token.
Two methods are available to obtain a OnePub Token.
After creating your CI/CD member (as described above) you can export the OnePub token from the Members page.
Clicking the 'Export Token' button will copy the OnePub token to the clipboard. You need to be an Administrator
To export a OnePub token from the CLI:
Obtain the email address of the CI/CD User from the Members page.
Login to the CLI of your local machine:
Now you have a OnePub token you are ready to import it into your CI/CD environment.
Your OnePub token is an access token and as such MUST be treated as a secret.
If you accidentally leak your token you can invalidate it from the Members page 'Invalidate Tokens' button.
You will need the OnePub CLI tools deployed as part of your CI/CD infrastructure so that your CI/CD environment can access your private packages hosted on onepub.dev.
To include OnePub into your build/test scripts you will need to install the onepub CLI tooling and ensure that the dart .pub-cache/bin is on your PATH.
How you add the .pub-cache/bin directory to your PATH will depend on your test environment OS.
The next step is to decide where to store your OnePub token and therefore which method you will use to import the token.
The onepub import command can import the OnePub token from an environment variable called ONEPUB_TOKEN.
This is an excellent method as many tools such as GitHub actions allow you to populate an environment variable from their secret store.
Change the above example from:
to
OnePub can import a OnePub token from a file.
OnePub does NOT recommend this method as it requires that you add your OnePub credentials to your source control system. However, if your CI/CD environment doesn't provide a method to store a token securely then this is the process you need to employ.
You can create the file when you export your OnePub token via:
The file will be called onepub.token.yaml and contain a single line:
Alternatively, you can manually create the file.
Change the above example from:
to
If you are using a local Docker instance to run unit tests please refer to the Docker section for some alternate methods.
If your CI/CD environment is going to publish a package into OnePub then the owner of the OnePub Token must be an owner of that package.
A package owner is one of, Administrator, Team Leader (when the package is associated with that team) or an Uploader. An Uploader can upload a package to any team they are associated with.
When publishing a package the 'dart pub publish' command will prompt the user to confirm the act of publishing. When running a CI/CD action there is no user involved, so you need to use the --force switch:
If the package you are building has a dependency (or a transitive dependency) on one of your private packages then the owner of the OnePub Token must belong to a team(s) that is associated with each of the dependent packages.
If you are on the Free or Pro subscription tier there is only one Team (called Everyone) and every member belongs to that team. With the Free tier, every member is an Administrator.
Whilst you can use any Member account in your CI/CD environment we recommend you created a dedicated CI/CD account.
The process for using an existing Member account (such as your own) are exactly the same as the processes described above, except that you use your OnePub token which can be obtained by running:
onepub export
There are several advantages to using a dedicated CI/CD account.
We recommend that you create a specific OnePub member for use in your CI/CD environment to reduce the risk of breaking your CI/CD environment if a regular member's permissions change.
1) a member logout won't break your CI/CD environment.
The onepub logout logs a user out of ALL of their devices including the CI/CD environment.
This means that if the owner of the shared account logs out of their onepub account then they will inadvertently invalidate the OnePub token used by the CI/CD environment.
2) The CI/CD environment permissions will be affected by any permission changes to the member. This can result in the CI/CD environment being given too many permissions or too few.
The only disadvantage is that using a separate CI/CD member does mean that you need to purchase an additional OnePub license.
