From 91399ac84926b03dc1cdab979024e1ba3817295c Mon Sep 17 00:00:00 2001 From: David Beitey Date: Thu, 25 Jan 2024 11:48:23 +0000 Subject: [PATCH] Update README to clarify API token and permissions required [semver:patch] (#110) * Update README to clarify API token and permissions required Fixes #103. Note that the CircleCI documentation is scant on information about what permissions are required to query and cancel jobs, but in testing in the UI at least, a user with Viewer access cannot cancel another user's running job, suggesting that Contributor (write access) is required for this orb to operate. * Update @orb.yml --------- Co-authored-by: Eddie Webbinaro --- README.md | 2 +- src/@orb.yml | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b01e4ab..1a7034c 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ See https://github.com/eddiewebb/circleci-challenge as an example using blue/gre ## Basic Usage -This adds concurrency limits by ensuring any jobs with this step will only continue once no previous builds are running. It supports a single argument of how many minutes to wait before aborting itself and it requires a single Environment Variable `CIRCLECI_API_KEY` - which can be created in [account settings](https://circleci.com/account/api). +This adds concurrency limits by ensuring any jobs with this step will only continue once no previous builds are running. It supports a single argument of how many minutes to wait before aborting itself and it requires a single Environment Variable `CIRCLECI_API_KEY`, which must be a **Personal API Token** (rather than a project-specific API Permissions token). This can be created at [Personal API Tokens](https://app.circleci.com/settings/user/tokens) under Users Settings. Note that the account must have write access (at least the **Contributor** role) on the Project you wish to enable this orb for. However, if the `dont-quit` parameter is enabled, view-only access (the **Viewer** role) is sufficient. ## Screenshots / Examples diff --git a/src/@orb.yml b/src/@orb.yml index df43ba9..02522e4 100644 --- a/src/@orb.yml +++ b/src/@orb.yml @@ -3,9 +3,11 @@ description: | Allows jobs or entire workflows to be queued to ensure they run in serial. This is ideal for deployments or other activities that must not run concurrently. May optionaly consider branch-level isolation if unique branches should run concurrently. - This orb requires the project to have an API key in order to query build states. + This orb requires the project to have an **Personal** API key in order to query build states. It requires a single environment variable CIRCLECI_API_KEY which can be created in account settings - https://circleci.com/account/api. + + 2.2.2: Docs clarity on token needs (@davidjb) 2.2.1: fixes release version bug 2.2.0: Adds 'filter-by-workflow' (@soniqua) 2.0.0: Breaking change fixes dyanamic config, but may break Bitbucket users.