go-vela / docs Goto Github PK

I think it would be helpful for companies coming into this repo to have a Install tab instead of Administration. Yes, it is an administrative task to install, but if you are looking how to install, most open source projects have the install instructions under a section called Install. For reference, I checked https://drone.io and https://jenkins.io and they both have a Documentation section and under the Documentation section there is a section referring to "Installing" or "Installation".

Please don't place EXE's in C:\Windows\System32. It's a OS folder and while it makes it easy to make your executable accessible as it's included in the System Path it's not the correct approach for several reasons.

• It obfuscates the origin of your executable and can be interpreted as malware.
• It requires that users have Administrative rights to modify

The best approach is to create an installer so that it can be installed to Program Files. The next best approach is for the user to place in into a directory of their choosing, such as their user profile, and update the User Path so that it's accessible from anywhere for that user.

https://github.com/go-vela/docs/blob/master/.github/DOCS.md

The sample template w/ a loop actually own't compile because of a scoping issue. When inside of a range the . changes to take on the elements of the array and thus .pull_policy errors out with something like:

unable to process webhook: unable to compile pipeline configuration for Username/Repo: unable to execute template ... executing "loop template test" at <.pull_policy>: can't evaluate field pull_policy in type interface {}

...
  {{ range $key, $value := .images }}

  - name: test{{ $key }}
    commands:
      - go test ./...
    image: {{ $value }}
    {{ .pull_policy }}
    ruleset:
      event: [ push, pull_request ]

  {{ end }}
...

To fix this I believe it simply needs to look more like:

...
  {{ range $key, $value := .images }}

  - name: test{{ $key }}
    commands:
      - go test ./...
    image: {{ $value }}
    {{ $.pull_policy }}
    ruleset:
      event: [ push, pull_request ]

  {{ end }}
...

The docs for Golang's text template explain it a little bit more too. https://golang.org/pkg/text/template/
Note the difference really is just the addition of $ before the . inside of the range loop.

On https://go-vela.github.io/docs/cli/authentication/#configuration-file the docs list:
vela login --api.addr <vela server url> and vela generate config --api.addr <vela server url> --api.token <personal token> but the flags beginning with api do not exist, and should be:
vela login --addr <vela server url> and vela generate config --addr <vela server url> --token <personal token>

vela version 0.4.1

The writing a pipeline link returns a 404. I could not find a link to this page anywhere else, so not sure it exists

Description

What is your idea?

Add information on how to paginate through multi-page results with the CLI

Value

Why is this important? Who does it impact? Will this make something better, faster, etc?

To let users know that there's a way to get to further results

Definition of Done

What is the end goal of this story?

Information about the pagination parameters is added to the docs

Effort (Optional)

Estimated effort to complete this story? (Best Guess e.g. 1-2 days)

1 day

Impacted Personas (Optional)

Which personas will benefit from completing this story? (Users, Administrators, etc)

Users

This may be obvious to some, but a nudge in the right direction on how to decode the response data in the log section and step log section would be extremely helpful for people wondering how to access data.

Description

What is your idea?

Value

Why is this important? Who does it impact? Will this make something better, faster, etc?

Definition of Done

What is the end goal of this story?

Effort (Optional)

Estimated effort to complete this story? (Best Guess e.g. 1-2 days)

Impacted Personas (Optional)

Which personas will benefit from completing this story? (Users, Administrators, etc)

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update dependency axios to v1.7.7
• chore(deps): update actions/checkout action to v4
• chore(deps): update actions/setup-node action to v4
• chore(deps): update peaceiris/actions-gh-pages action to v4
• chore(deps): update peaceiris/actions-hugo action to v3
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

https://go-vela.github.io/docs/installation/server/docker/

Documentation doesn't clearly or fully explain what would the values of these if you are trying to setup Vela in your local desktop environment ?

Server
VELA_ADDR
VELA_WEBUI_ADDR

https://go-vela.github.io/docs/installation/worker/docker/
Worker
VELA_WORKER_ADDR

https://go-vela.github.io/docs/installation/ui/docker/
UI
VELA_API

For installation and usage, please visit our user docs.

Where is the installation info ? how will a beginner find info on how to install.

I have spent hours on trying to figuring out the installation guide, but in the whole of website there is none.

Why was this even thought of ? If there is no installation guide what kind of expectation is needed for a beginner to find out the info ?

Or is there a service fee for it ?

Background
When reading the example provided in the pipeline stages needs documentation, it is not obvious that the stage name is used for the needs value rather than the stage key.

Explanation
The following pipeline works, which is described in the documentation:

stages:
   foo:
      steps:
         - name: step-1
            image: golang
            ...
   bar:
      needs: foo
      steps:
         - name: step-2
            image: golang
            ...

However, the following will not have the stage dependency:

stages:
   foo:
      name: "Foo stage"
      steps:
         - name: step-1
            image: golang
            ...
   bar:
      needs: foo
      steps:
         - name: step-2
            image: golang
            ...

This will only work if the stages.bar.needs value is set to"Foo stage".

It would be nice if the stage key (e.g. foo) could be used, rather than the override name that's intended for UI formatting.

Description

Right now the CLI docs don't talk much about adding an organization level secret - https://go-vela.github.io/docs/cli/secret/add/

Value

Organization level secrets are great because everything can fall in one place instead of managing secrets at one level. Telling people how to do this since it isn't super intuitive would be good.

Definition of Done

Documentation is updated

Effort (Optional)

1 hour

Impacted Personas (Optional)

Users

Can this page be updated to match the documentation provided by the drone substitution library that is used by vela? The current documentation does not provide enough detail.

https://github.com/drone/envsubst

In my experience, you can't map the ports like "9080:8080"

Assuming that is correct, perhaps the docs could mention this.

Expected:

Link at

Should work

Actual:

404

The link is https://github.com/go-vela/community/issues/new . I don't see a "community" repo

Consider enumerating the different methods to retrieve the token to use in API calls and add them to: https://go-vela.github.io/docs/api/authentication/

The example docs show lint-skip being used with id numbers, that I couldn't find anywhere, even after looking at the source. I tried using names, ie: no-changed-when, and that worked. Unsure if numeric ids are still available for this and I've yet to discover them, or if names should be used instead.

    parameters:
      action: lint
      playbook: "ansible/playbook.yml"
      lint_skip:
        - no-changed-when

It would be helpful to have an example of Vela's response with an incorrect validation file; only a valid response is listed currently
https://go-vela.github.io/docs/usage/reference/cli/validate/#sample

I have tried all the steps that are mentioned in the https://go-vela.github.io/docs/installation/ but I am not able to setup as the instructions only link if you have real IP Addresses.

How should one setup in local(Not for contribution or development) but just to play with it ?

I have tried it here and posted an issue also,
go-vela/community#738

When trying to read up on vela templates and how they work I ended up on the templates section and the tutorial. Upon wanting to find out more about the source tag I couldn't find any relevant information; I think it would be handy to link to the reference documentation from the tutorial root to make it more discoverable.

I had noticed that older secrets were no longer appearing on my list when doing vela get secret --org data-engineering-fieldops --type org --repo '*'. After posting this to #vela on Slack, I came to learn about two flags which are not documented. These do allow me to view secrets beyond my initial page, so should be added to the documentation https://go-vela.github.io/docs/cli/secret/:

--page
--per-page

A useful feature of vela is being able do templating in the same .vela.yml file, it would be great to have a reference to https://go-vela.github.io/docs/templates/#templating-directly-in-velayml in the usage examples

https://go-vela.github.io/docs/usage/reference/cli/validate/#sample

The actual message returned by my running of the command is:
Config is valid.

Please update documentation on how to get started. :)

Many descriptions of variable substitution are vague. It looks like the substitution follows bash 4.0 rules but is unclear. A link to bash explanations of substitutions, if valid or describing the substitutions would be greatly appreciated.