> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# eddiewebb/queue

DEPRECATED:

Users should adopt CircleCI's native `serial-group` stanza instead. (See docs).


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 optionally consider branch-level isolation if unique branches should run concurrently. 
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.

3.3.3/ 
3.3.2: Goodbye world! 
       Serialization is now native in CIrcleCI's serial-group stanza!
       <3 Thanks to all who made that happen, including every user of this orb.
3.3.1: Calculate wait time via wall clock, PR#140, thanks @jordan-brough
3.3.0: Add timestamps to output, PR#139, thanks @jordan-brough
3.2.1: Docs improvement, PR #136 Thanks @RainOfTerra
3.2.0: Adds back-off support to handle 429 throttling from new API. PR #134  Thanks @rainofterra
3.1.6: Fix #128 again, this time on JQ side. PR #133 Thanks @RainOfTerra
3.1.5: Fix #128: allow spaces in job names and other bash bugs in PR #131, thanks @RainOfTerra
3.1.4: Fix missing branch error when using tags. Issue #126
3.1.2: Fix github VCS switch (API calls failing) thanks @risinga PR #122
3.1.1: Boolean fix finally isolated, thanks @@charlescqian
3.1.0: Force fail, not cancel, when blocked. PR #113, thanks @pguinard-public-com
3.0.0: [BREAKING CHANGE] Use pipeline.number as authoritative comparison. Deep thanks to @PChambino
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. 
1.12.0: Adds Server Support (@nanophate)
1.9.0: Doc update
1.8.4: Adds urlencode for branch names. (@andrew-barnett)
1.8.1: Adds content-type header to API calls (@kevinr-electric) and prints message on error (@AlexMeuer)
1.8.0: minor fix same as version 1.8.0 (missing docs)
1.7.1: patch fix same as version 1.8.1 to catch folsk who dont update
1.7.0: adds regexp for job names, collab with @jonesie100
1.6.5: docs contribution by @pwilczynskiclearcode 
1.6.4: support slashes in Tags, thanks @dunial
1.6.3: addresses API changes that broke branch-job queueing, adds more API checks
1.6.1: fixes issue in tag matching , thanks @calvin-summer
1.6.0: Support Tags, thanks @nikolaik, @dunial
1.5.0: API variables name as parameter , thanks @philnielson
1.4.4: Docs improvements, thanks @jordan-brough
1.4.3: more confident confidence thanks @GreshamDanielStephens
1.4.2: Doc improvements, thanks @olleolleolle
1.4.1: fixes bug in block-workflow as job. thanks @mu-bro
1.4.0: Adds confidence checks to avoid race condition 
1.3.0: use small resource class in job


## Commands

### until_front_of_line

| Parameter | Type | Default | Description |
|---|---|---|---|
| `block-workflow` | boolean | false | If true, this job will block until no other workflows with ANY JOBS with an earlier timestamp are running. Typically used as first job. |
| `circleci-api-key` | env_var_name | CIRCLECI_API_KEY | In case you use a different Environment Variable Name than CIRCLECI_API_KEY, supply it here. |
| `circleci-hostname` | string | circleci.com | For server user to specifiy custom hostname for their server |
| `confidence` | string | 1 | Due to scarce API, we need to requery the recent jobs list to ensure we're not just in a pending state for previous jobs.  This number indicates the threhold for API returning no previous pending jobs. Default is a single confirmation. |
| `dont-quit` | boolean | false | Quitting is for losers. Force job through once time expires instead of failing. |
| `fail-instead-of-cancel` | boolean | false | Fail this command instead of canceling. |
| `force-cancel-previous` | boolean | false | No Mercy. Issue cancel commands for any previous competitors (only applies when dont-quit also true) |
| `include-debug` | boolean | false |  |
| `job-regex` | string |  | Used to selectively block individual jobs in a workflow. ex '^deploy*' |
| `limit-branch-name` | string | * | Only apply queue logic on specified branch.  |
| `limit-workflow-name` | string | * | Only queue on a specified workflow. Consider combining this with `this-branch-only`:`false`. |
| `max-wait-time` | string | 10 | How many minutes to wait before giving up. |
| `my-pipeline` | integer |  |  |
| `tag-pattern` | string |  | Set to queue jobs using a regex pattern f.ex '^v[0-9]+\.[0-9]+\.[0-9]+$' to filter CIRCLECI_TAG |
| `this-branch-only` | boolean | true | Should we only consider jobs running on the same branch? |

## Jobs

### block_workflow

| Parameter | Type | Default | Description |
|---|---|---|---|
| `block-workflow` | boolean | true | If true, this job will block until no other workflows with an earlier timestamp are running. Typically used as first job. |
| `circleci-api-key` | env_var_name | CIRCLECI_API_KEY | In case you use a different Environment Variable Name than CIRCLECI_API_KEY, supply it here. |
| `circleci-hostname` | string | circleci.com | For server user to specifiy custom hostname for their server |
| `confidence` | string | 1 | Due to scarce API, we need to requery the recent jobs list to ensure we're not just in a pending state for previous jobs.  This number indicates the threhold for API returning no previous pending jobs. Default is a single confirmation. |
| `dont-quit` | boolean | false | Quitting is for losers. Force job through once time expires instead of failing. |
| `fail-instead-of-cancel` | boolean | false | Fail this command instead of canceling. |
| `force-cancel-previous` | boolean | false | No Mercy. Issue cancel commands for any previous competitors (only applies when dont-quit also true) |
| `include-debug` | boolean | false |  |
| `job-regex` | string |  | Used to selectively block individual jobs in a workflow. ex '^deploy*' |
| `limit-branch-name` | string | * | Only apply queue logic on specified branch.  |
| `limit-workflow-name` | string | * | Only queue on a specified workflow. Consider combining this with `this-branch-only`:`false`. |
| `max-wait-time` | string | 10 | How many minutes to wait before giving up. |
| `my-pipeline` | integer |  |  |
| `tag-pattern` | string |  | Set to queue jobs using a regex pattern f.ex '^v[0-9]+\.[0-9]+\.[0-9]+$' to filter CIRCLECI_TAG |
| `this-branch-only` | boolean | true | Should we only consider jobs running on the same branch? |

## Examples

### multiple_job_names_regexp

Use regexp-jobname when you have multiple jobs to block order of.

```yaml
version: '2.1'
orbs:
  queue: eddiewebb/queue@volatile
jobs:
  DeployStep1:
    docker:
      - image: circleci/node:10
    steps:
      - queue/until_front_of_line:
          job-regex: ^DeployStep[0-9]$
          limit-branch-name: main
          max-wait-time: '10'
          my-pipeline: <<pipeline.number>>
      - run: >-
          echo "This job will not overlap with itself or next similar nameds
          job"
  DeployStep2:
    docker:
      - image: circleci/node:10
    steps:
      - run: echo "This job will block step1 on any further workflows"
  build:
    docker:
      - image: circleci/node:10
    steps:
      - run: echo "This job can overlap"
workflows:
  build_deploy:
    jobs:
      - build
      - DeployStep1:
          requires:
            - build
      - DeployStep2:
          requires:
            - DeployStep1
```

### queue_workflow

Used typically as first job and will queue until no previous workflows are running

```yaml
version: '2.1'
orbs:
  queue: eddiewebb/queue@volatile
workflows:
  build_deploy:
    jobs:
      - queue/block_workflow:
          limit-branch-name: main
          max-wait-time: '10'
          my-pipeline: <<pipeline.number>>
      - some_other_job:
          requires:
            - queue/block_workflow
```

### single_concurrency_job

Used to ensure that a only single job (deploy) is not run concurrently. 
By default will only queue if the same job from previous worfklows is running on the same branch. 
This allows safe jobs like build/test to overlap, minimizing overall queue times.


```yaml
version: '2.1'
orbs:
  queue: eddiewebb/queue@volatile
jobs:
  build:
    docker:
      - image: circleci/node:10
    steps:
      - run: echo "This job can overlap"
  deploy:
    docker:
      - image: circleci/node:10
    steps:
      - queue/until_front_of_line:
          limit-branch-name: main
          max-wait-time: '10'
          my-pipeline: <<pipeline.number>>
      - run: echo "This job will not overlap"
workflows:
  build_deploy:
    jobs:
      - build
      - deploy:
          requires:
            - build
```