Workflow Doc Examples incomplete


#1

The workflow documentation simplifies the syntax to the point that it is not usable. Do CircleCI users already expect each job to checkout its own copy of the code or explicitly copy all necessary files to a workspace? As a new CircleCI user this seems like a significant amount of boilerplate.

Is there a method to simply propagate the working directory? This cannot be done by reusing job steps, because you cannot use a yaml reference in an array (I tried though)

Is the workspace documentation correct?

Subissue: The persist_to_workspace schema does not match the example.

Taking the first example and modifying it with “real” values:

version: 2
jobs:
  build:
    working_directory: ~/app
    docker:
      - image: circleci/python:3.6.1
    steps:
      - checkout
      - run: ls -al
  test1:
    steps:
      - run: ls -al
  test2:
    steps:
      - run: ls -al
  test3:
    steps:
      - run: ls -al
workflows:
  version: 2
  build_and_test:
    jobs:
      - build
      - test1
      - test2
      - test3

Results in the following error:

Build-agent version 0.0.3462-5a15665 (2017-07-04T02:22:51+0000)
Configuration errors: 1 error occurred:

* 3 errors occurred:

* In job 'test2': 3 errors occurred:

* missing executor type
*  is not supported executor type
* no working_directory
* In job 'test3': 3 errors occurred:

* missing executor type
*  is not supported executor type
* no working_directory
* In job 'test1': 3 errors occurred:

* missing executor type
*  is not supported executor type
* no working_directory

Adding executors without painful duplication gets past the schema errors. Of course there could be different images for every job.

defaults: &DEFAULT
  working_directory: ~/app
  docker:
    - image: circleci/python:3.6.1

version: 2
jobs:
  build:
    <<: *DEFAULT
    steps:
      - checkout
      - run: ls -al
  test1:
    <<: *DEFAULT
    steps:
      - run: ls -al
  test2:
    <<: *DEFAULT
    steps:
      - run: ls -al
  test3:
    <<: *DEFAULT
    steps:
      - run: ls -al
workflows:
  version: 2
  build_and_test:
    jobs:
      - build
      - test1
      - test2
      - test3

But there are no files to test against without another checkout or use of a workspace (mentioned as a subtopic of the 5th example, but not a primary topic):

defaults: &DEFAULT
  working_directory: ~/app
  docker:
    - image: circleci/python:3.6.1

version: 2
jobs:
  build:
    <<: *DEFAULT
    steps:
      - checkout
      - persist_to_workspace:
          # root: workspace <- This is not in part of the documented schema
          paths:
            - echo-output
  test1:
    <<: *DEFAULT
    steps:
      # Need another checkout
      - checkout
      - run: [[ ! -f README.md ]] && echo "Incomplete Docs: Missing README.md" && exit 1
  test2:
    <<: *DEFAULT
    steps:
      # Or need a workspace
      - attach_workspace:
          at: ~/app
      - run: [[ $(cat echo-output) == "File-for-linting" ]] || echo "Failed"; exit 1
  test3:
    <<: *DEFAULT
    steps:
      - run: ls -al
workflows:
  version: 2
  build_and_test:
    jobs:
      - build
      - test1
      - test2
      - test3

This gets stuck trying to spin up the environment without a clear error:

Build-agent version 0.0.3462-5a15665 (2017-07-04T02:22:51+0000)
Configuration errors: 2 errors occurred:

* error parsing config: yaml: line 27: did not find expected comment or line break
* job 'build' is not found

#2

I think I’ve been having the same issue as you. It seems even the default documentation is incorrect.

As a new user I expected to be able to have 1 job that “builds” the container with the code & dependencies, then have separate follow up jobs run different test suites in copies of that first container. This is something buildkite’s docker setup does really well - the build job creates an image from the container and pushes it to a repo. It takes care of giving each image a build-specific name, and ensuring subsequent steps use the right image.

The documentation I linked to seems to imply what I want to do is possible, it’s just that the app doesn’t allow this to happen. :pensive:


#3

Thank you so much for your feedback. Sorry that you are having trouble getting started with Workflows. I will work with our team to improve our documentation and provide functional examples. We have added some examples around Workflows functionality here. Please reach out to us at support@circleci.com if you are still facing issues. Thank you so much for your patience.


#4

The workspace-forwarding example is still broken

Error locating workspace root directory: stat ~/my-working-dir: no such file or directory

Workspace forwarding is documented in several places, all differently, and all wrong.


#5

I am facing the exact same issue, tried to follow the examples and nothing worked. I don’t really understand why it is required to write so much boilerplate. It would be much better if working_directory as well as this workspace management has some sane defaults. Just changing into an empty directory should be enough for steps that really require a clean slate.

Would be great if you overthink these decisions.


#6

Hello!

Could you take a look at this example and see if it makes sense to you?

Happy to answer any questions!


#7

Thanks for pointing out the workflow examples.

I was unable to get the workflow examples to work either. If a build job is present then it is run, but not the remainder of the steps in the workflow. If no job named ‘build’ is present then no jobs are run and the “job ‘build’ is not found” configuration error is raised.


#8

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.