HN Theater @HNTheaterMonth

⬐ pm90

I would hesitate to build on anything that relies on GitHub native tooling. GitHub support is absolutely the worst. Their tools fail in weird ways at times, and without support you will be stuck. For personal/non production apps, fine. But beware of using it as a core part of your infrastructure.

⬐ penagwin

Thanks for the warning, are there any good tools that integrate with pull request checks that can be self hosted?

We self host nearly everything at work except for github. (And it's VERY difficult for me to get anything that costs money approved regardless of price)

⬐ ethomson

Product Manager for GitHub Actions here. You can self-host the GitHub Actions runners. This means that you can run CI/CD workflows on your own hardware, while your source code is hosted on github.com itself. https://help.github.com/en/actions/automating-your-workflow-...

⬐ petrikapu

Can you give some insight when shared self-hosted for private repos are available? It was super easy to setup for single project. I’d like to share beefy AWS instance for few more private repos. Keep on good work!

⬐ penagwin

We're currently trying to use Github Actions but we've run into a few issues. The first is that when our team members push pull requests from their forked branches it doesn't trigger checks on the pull request. I understand this is for security reasons, but in our case the repository is private and all forks are considered trusted.

The other is that there's currently no way to label specific workers. Because of how our network/firewall is segmented we would like to be able to specify a worker for Staging/Dev/Production separately. The closest thing I found was this [0] pull request from October, but it doesn't add the ability to add custom labels.

Is there any timeline for either of these features (especially the labels)?

[0] https://github.com/actions/runner/pull/130

⬐ wilsonrocks

Gitlab let's you do an awful lot and can be self hosted.

⬐ disconnected

> Thanks for the warning, are there any good tools that integrate with pull request checks that can be self hosted?

Recently at work we've done an analysis of a of CI/CD tools. Many of them are self-hosted, free (and open source) and support a variety of workflows - including pull request related checks (either by polling of via webhooks). A cursory search will yield you a lot to play with, so... go ahead and do that.

That said, if you don't want to think about it too much, you can't go wrong with Jenkins.

Some people will suggest GitLab. I'd steer clear of GitLab, though, because of their operational incompetence [1] and their funny ideas about mandatory corporate espionage [2] - I mean, telemetry - which they only backed away from because people yelled at them. That second one was enough to disqualify them in our analysis (the first one just cemented the idea).

[1] https://about.gitlab.com/blog/2017/02/10/postmortem-of-datab...

[2] https://www.theregister.co.uk/2019/10/30/gitlab_backtracks_o...

⬐ mnutt

It seems like their gitlab.com uptime isn't that relevant when the question was about self-hosted CI. And while I don't like the idea of telemetry in self-hosted products either, calling it "corporate espionage" is hyperbole and I don't know how much more one could expect from their response other than apologizing and backtracking.

⬐ 0xEFF

Gitlab CI is great if you need only one pipeline to execute per branch.

As soon as you need multiple pipelines per branch it doesn’t work well.

Most small projects need only one pipeline and are well suited. Other things like terraform needing multiple pipelines for multiple environments are better suited for a CI platform that handles multiple pipelines.

⬐ prophetjohn

It costs money, but for other readers, I've been using Buildkite[0] at two different companies across ~4 years now and it's great. It's _mostly_ self-hosted in that jobs run on your own hardware and Buildkite itself is only the job queue that your self-hosted agents pull work from. They also provide an elastic CI stack[1] so you can have auto-scaling workers running on AWS

You still own enough of it that if the service is down, you can just execute the scripts manually to build, test and deploy

[0] https://buildkite.com [1] https://github.com/buildkite/elastic-ci-stack-for-aws

⬐ xtracto

I echo the Gitlab recommendation. Setting up CI/CD pipelines is beautifull, easy and all code-backed. And you can self hist it.

Really. Having one repo checked out into a docker container with a specific node version toolchain and running your test suite with code coverage + publishing html reporting is a matter of a .gitlab_ci.yml config file with 6 to 10 lines .

⬐ bravura

And it's VERY difficult for me to get anything that costs money approved regardless of price

For me, this is a big red flag.

⬐ penagwin

I should probably emphasize that it's difficult for me to get new things approved, but if we NEED it then money is not a problem.

The response I get is we don't _NEED_ a CI/CD (and haven't had one for years), so they would rather I find a solution that can run on our hardware for free.

I'll add that I enjoy my work environment and they treat me very well, I'm young and I'm known to "like shiny new things". I also have to work on how I pitch why we need certain things, again I'm pretty young so I'm not well practiced in that just yet.

⬐ wasyl

For a free, self-hosted CI I strongly recommend TeamCity -- if you can get away with 3 build agents and 100 configurations that come with the free version.

I was in your boots some time ago, managing CI before I convinced the company that paying for a hosted CI is cheaper than me maintaining our self-hosted whatever CI we were trying at that point :) Jenkins was atrocious and I spent ungodly amount of time dealing with all kinds of issues, while TeamCity was mostly configure-and-forget. Initial setup is pretty straightforward, so is later migration to a real database for example. Updates are seamless and we had some projects on it even after we started using paid CI (Bitrise), because there was no motivation to migrate as everything was running smoothly.

⬐ jrochkind1

> The response I get is we don't _NEED_ a CI/CD

You are not making this sound like less of a red flag!

But yeah, if you are both new and young there, you can't just push hard for all the things you want. But in this case... you're right, heh.

If I were you, I'd be keeping my eyes out for job opportunities in environments where you can actually learn something about good modern software engineering practices form their example. (Easier said then done, don't I know it).

⬐ kureikain

Github actions is nice but I think they go to wrong direction. The way they work is you are given an image then you have to use a thing call Github action, which basically just to extract out into YAML to define a certain steps for install any dependencies, execute shell script ...

I don't know why they didn't allow us to use any docker image we want so we don't have to waste time to use actions to install dependencies...Eg, if your app depend on both Go, Ruby, Node at build time you will need:

https://github.com/actions/setup-go https://github.com/actions/setup-node https://github.com/actions/setup-ruby

I much prefer CircleCI way

⬐ ReidZB

I'm not sure if this is the 'right way' or not, but for a recent Go project, I just scripted the build via

    - name: build
      run: |
        docker run --rm -v \
          "$PWD":/usr/src/my-project \
          -w /usr/src/my-project \
          -e GOOS -e GOARCH \
          golang:1.13 go build -v -o my-project-$GOOS-$GOARCH
      env:
        GOOS: ${{ matrix.os }}
        GOARCH: ${{ matrix.arch }}

(GitHub Actions's build environment already has Docker installed/configured, so there's no setup necessary for "run: docker run" to work.)

I did this explicitly because I didn't want to use that "setup-go" action you linked, which at the time (I haven't doubled checked it recently) didn't support Go 1.13. Far better to me to use the Docker image, which has explicit instructions even for cross-platform compilation in its README, than rely on some weird action setup, in my opinion.

⬐ tomphoolery

I like this approach as well, though I typically include a `Dockerfile` in my Go projects so my run task is just:

    - name: Build
      run: docker build -t me/image:latest .
      env:
        DOCKER_BUILDKIT: 1
        GOOS: ${{ matrix.os }}
        GOARCH: ${{ matrix.arch }}

⬐ ReidZB

Ah, well, the output of what I wrote above isn't actually a Docker image. It ends up writing a cross-compiled binary to the local FS, which I then later attach to a GitHub Release. (The goal was to automatically attach platform binaries to a release once it was made.)

...unless your Dockerfile ends up doing that too? If so I'd be interested to see it if you're willing to share!

⬐ judge2020

You can use an arbitrary container: https://github.com/judge2020/test-actions2/blob/master/.gith... - https://github.com/judge2020/test-actions2/commit/5732cd3496... although I admit it's slower than CircleCI's runners.

⬐ stevekemp

My approach to this was to create generic images. For example there are various actions out there to "Run `make test`", "Run pytest", or "Run go tests".

Why be specific? Why not include a shell-script in your repository, and allow that to run the tests? That way you just need one "Run test-script" action:

https://github.com/skx/github-action-tester

⬐ tracker1

I've done pretty much just this... choosing the appropriate OS image(s) and relying on a given scripting language in the environment.. the scripts themselves are in code and the YAML us just enough to run what's needed.

https://github.com/bbs-io/syncterm-windows/blob/master/.gith...

⬐ kwhat4

> I don't know why they didn't allow us to use any docker image we want

Can you imagine allowing anyone on the internet to run an arbitrary container on your server for free?

⬐ pushpop

Many services already do allow this; including the aforementioned CircleCI

⬐ xtracto

Confirming that most other Ci services allow you to do that. I have done it in Gitlab for the Ci/CD of my Ionic apps.

⬐ jrockway

That is what every CI service in the world is. Docker doesn't intrinsically give you any privileges a shell script doesn't, but there is flexibility to really lock things down (like with gVisor). Of course, a lot of people run the Docker daemon in such a way as to give containers root access, which isn't ideal in a shared environment. There is no mandate to do such a thing, however.

I built an old-style Docker container (i.e., one that runs code like "apt-get install foo") on Github Actions successfully, so I assume Docker works fine. I haven't tried getting root on a build worker, but I imagine they mitigate that in some way. (Perhaps by having a pool of VMs and blowing it up after your build is done.)

I think what the OP is talking about is CI systems whose pipelines are declared by a series of "run this command in this container" instructions. Github Actions doesn't work that way, but you can still run containers.

⬐ manigandham

We use Buddy: https://buddy.works/

Each step of a pipeline is just a docker container of your choice and running whatever commands you want with a persistent workspace volume throughout the pipeline.

There's a few others that work this way like Semaphore, Drone CI, GoCD, CircleCI, Azure Devops but none are as fast, seamless and easy as Buddy.

⬐ slow_donkey

Your link blasts a song on click

⬐ JMTQp8lwXL

It could be intentionally locked-in using the Action YAML. The proprietary nature could help with profits.

⬐ ethomson

If you want to run within a container so that you don't have to install dependencies, that's no problem. Just specify it as `jobs.<job-id>.container`. GitHub Actions will download and start that container, and any `run` commands that you specify within that job will run within that container.

Without that, they'll run directly on the virtual machine that you specify.

⬐ jhasse

> Just specify it as `jobs.<job-id>.container`.

I don't know what this means. Are there any examples?

Running in a container is the one big thing I'm missing and couldn't find any documentation about.

⬐ ethomson

Here's an example: https://www.edwardthomson.com/blog/github_actions_5_building...

⬐ keyP

The GitHub Actions Runner has just been open sourced https://github.com/actions/runner

⬐ ioquatix

That's awesome, thanks for the link. I made an AUR package: https://aur.archlinux.org/packages/github-actions/

⬐ ShakataGaNai

Maybe it's changed in the last month or two, but last time I looked at GitHub actions I couldn't find a single example of "Build docker container and push to GitHub Packages".

There are a lot of cool examples demo'ing some nifty stuff, but I'd like to see a lot of very basic examples first. The sort of thing anyone could/would copy into their project and use, then later learn how to make it fancy.

⬐ itcrowd

What's up with so many YouTube video's (including this one) having ALL CAPS titles?! It makes me not want to watch them, although it may be different for the general public for some reason ... ??

⬐ kej

It's because

YOU WILL NOTICE THIS ONE

in a list of

other normal text

⬐ gpu_explorer

But it doesn't work in Hebrew.

⬐ wescarpenter

I GUESS WE'LL JUST

HAVE TO WAIT UNTIL

EVERY ONE LOOKS LIKE THIS

so then this one

WILL STAND OUT AGAIN?

⬐ docuru

Click bait!

⬐ sharperguy

I've heard youtubers claim that YouTube's algorithms make it impossible to get views without using clickbaity titles.

E.g:

[1] https://www.youtube.com/watch?v=7i1IOO6g0vc

⬐ NikolaeVarius

This has been true of all media since the dawn of media. Youtube has nothing to do with it

⬐ kenver

We managed to move our iOS CI over to this in a couple of days. Produces multiple independent builds based on branch names, signed with an enterprise profile for testing and QA. These are uploaded and shared via ms app center. It also produces our App Store releases signed and uploaded to the App Store via a regular developer account.

The process was mostly just changing out a Jenkins file to the GitHub yml and sorting a few issues that cropped up.

⬐ pavlov

I'd be hesitant to build on GitHub tools that have overlap with anything Microsoft provides. When something similar is introduced to Azure, why keep the subsidiary's internal competition around?

This happened already with VS Code vs. Github's Atom editor whose development has ceased earlier this year. (Not that I ever was a huge fan of Atom, but its discontinuation is a direct result of the Microsoft acquisition.)

⬐ lioeters

> Github's Atom editor whose development has ceased earlier this year

It doesn't seem like they've ceased development on Atom - the latest version release was just 3 days ago? https://github.com/atom/atom/releases

---

I've started learning GitHub Actions, at first just for simple build/deploy script, but hope to make more extensive use of the feature.

I did consider how it overlaps with Microsoft's other business areas, and I came to the conclusion that they probably wouldn't be investing resources into this, just to sunset it anytime soon. (I'm sure there are historical examples though, like some Google products..)

In the end, I do somewhat share your hesitation, and believe it's a good idea to always be ready to migrate the essentials. For GitHub Actions, I suppose that means having most of the functionality written in generic scripts.

⬐ manojlds

It's not just a direct result. VSCode was already on way to make Atom defunct and the acquisition closed it earlier.

Also, GitHub Actions is based on Azure Pipelines already.

⬐ thinkingkong

Github actions is most definitely using Azure build pipelines behind the scenes. Microsoft is smart about boosting revenue figures. Id be shocked if this wasnt the case.

⬐ prepend

I am afraid that Microsoft will kill GitHub stuff in favor of azure stuff, but I think the risk is low because it seems like GitHub’s whole purchase was for goodwill.

If I had to bet, I think “azure devops” will go away and GitHub will eat it.

Currently the Actions free tier is cheaper than using azure build pipelines which is kind of weird, but nice for GitHub users. I think it’s because GitHub is a limited subset (ie, doesn’t need to support Windows IaaS build types) so it may be cheaper to run.

⬐ m_ke

I'm convinced their goal is to leverage GitHub to win the cloud wars and that they'll keep porting all of their Azure products onto it until GitHub is the cloud provider.

I bet we'll see a click to deploy button on github for most common web frameworks soon.

Having your git history hooked up to your deployed infrastructure will allow them to do some amazing things around live debugging. (similar to what google is doing with cloud source repositories https://cloud.google.com/debugger/).

⬐ amdelamar

Only thing I don't like about GitHub Actions so far is the YAML structure. e.g.

    name: master-pull-request
    on:
      pull_request:
        branches:
          - master
    jobs:
      test:
        name: run tests
        runs-on: ubuntu-18.04
        steps:
          - uses: actions/checkout@v1
          - name: Run gradle test
            run: |
              ./gradlew test

I much prefer Drone CI's YAML:

    kind: pipeline
    name: default
    steps:
      - name: run tests
        image: openjdk:8-jdk-slim # Docker images!
        commands:
        - ./gradlew test

⬐ edaemon

GitHub's format is like Drone's "multiple pipelines" feature in a single document instead of separate ones. Drone uses multiple documents that each define a different set of steps while GitHub does that in a single document with separate jobs.

It's just an issue of preference, I suppose, but I prefer GitHub's way of doing things. I find it easier to read and understand.

⬐ engineeroncall

While it’s not perfect, GitHub Actions was pretty straightforward to set up for an open source iOS project I help manage[0].

Most of the actions were pre-existing Makefile targets used during the bootstrap process anyway, so the YAML config was fairly lightweight.

Echoing the other comments in the thread, the docs did feel a bit sparse when I last poked around (this was back when Actions was still in beta).

[0] https://github.com/birdrides/mockingbird

⬐ louib

I had to setup CI for a GitHub open source project recently, and decided to give GitHub Actions a try. I have to say it's pretty nice to have the CI directly handled by GH (GitLab has been doing it for years, I know...). I hope it's gonna help some open source projects to easily add CI validations to their PR workflow.

That being said, there was only Ubuntu images for the Linux builds, and I'm not aware of a way to run custom containers at the moment.

⬐ ethomson

Indeed, GitHub Actions only has ubuntu virtual machines, but you can run a custom container with the `jobs.<job-id>.container` specifier.

⬐ jillesvangurp

Actually it' s possible to do react native builds on OS X as well: https://medium.com/@jonnyburger/first-look-using-github-acti...

We've been experimenting with this and are using this to add some CI to our react native frontend.

⬐ ethomson

Yes, I apologize for not being clear: our Linux virtual machines only run Ubuntu. (We also offer macOS and Windows virtual machines.)

⬐ reilly3000

Most of the Actions are actually custom containers. So to run your own code you can just make an action, which isn't that complex.

⬐ ethomson

PM for GitHub Actions here. I wouldn't suggest that you build an action to run a build within a container. We offer container support for workflow runs which should be suitable for this. (Either by specifying the `jobs.<job-id>.container` or by using `docker run ...`)

Actions themselves are meant to support the workflow and distill a set of complex steps into something that can be done in a single workflow command. (For example, download and set up a new version of a Java JDK.) They're meant to be used as steps in many peoples workflows, instead of executing a single workflow.

The actions themselves can be built as either a container, which is self-contained, or as JavaScript. I often recommend the latter, since that will work cross platform (containers only work for people who are using workflows running on Linux).

⬐ pyr0hu

I really liked GitHub's pipeline description file, but my issue with GH Actions was that the pipeline was slow. The same job running on the cheapest/slowest free-tier available Semaphore runner took half the time than on GitHub. That's with caching, parallelization on GH too.

Otherwise it could be a good product, and I'd really like if I could manage the repos and the CI from one unified place

⬐ k__

Tried it out a week ago, but the docs weren't too helpful and the build templates I found were buggy.

⬐ hanniabu

That seems to br the general sentiment in this thread. I hope somebody of power within Github is reading this, or someone that can pass the info along to such a person.

⬐ darkwater

Free? We are a paying Org and pushed a few test docker images (built via Actions) to the new Packages (aka GH docker registry) and you have just 2GB really free (well, included in your plan). Then you have to pay extra. We have like 80 accounts, already paying a lot of $$$ to GH and they give you 10000 minutes of free Actions - which is cool - but ONLY 2 freaking gigabytes of storage for free??

⬐ vageli

How do people test GHA before pushing to github? I encountered a tool or two to assist but they require the action to be described with HCL not the newer YAML syntax.

⬐ karaokeyoga

Outstanding video ... beginner-friendly, great signal-to-noise ratio, succinct, excellent visuals and a clear voice.

⬐ kmf

hey, thank you so much! I’m super proud of it, been trying to improve every aspect of my vids from scripting/storyboarding, recording, editing, etc - I think it all really came together well here!

⬐ NieDzejkob

@mods As far as I understand, this should be tagged as [video].

⬐ dang

Added. Thanks!

⬐ ifthenelseend

No VCS post without paid gitlab commentators... Propaganda department is working very hard!!

⬐ ccleve

I have spent the last two days fighting with these new Github tools. I've been trying to do a simple Hello-World Maven app, built on Github Actions and deployed to Github Packages. It does not work.

Github documentation is a disaster. They leave out critical parts. They don't provide examples. Everything they write is terse, confusing, and incomplete.

They have short little articles on how to do things, and for each sub-task they have a link to docs somewhere else. This would be fine, except the links don't point to anything useful.

To give an example: they say you can use the Github API to talk to Github Packages, but the link goes to their generic GraphQL documentation. They don't point to any reference material on the actual calls to the packages service. If it exists, I can't find it.

If you go to the main page in your account for Github Packages, it says that all you have to do is this:

mvn deploy -Dregistry=https://maven.pkg.github.com/mycompany -Dtoken=GH_TOKEN

That is just straight-out wrong. It does not work.

Seriously, Github, you need to fire your documentation team and hire some people who know how to write. Perhaps you should hire people who have actually used your tools to write the docs. Or just provide some freakin' working examples.

⬐ ComputerGuru

I am with you on this. It seems to be a new trend: “show users how to do a hello world” which was disregarded in the past... but somehow that turned into “instead of providing real documentation” rather than “in addition to.”

It’s not just GitHub. There’s a language I (and the rest of HN) love that has adopted “story format” for documentation but is missing real, hard technical documentation apart from method-level codedocs. It’s nice for building momentum but it leaves you unable to find a central location with an architectural documentation of the system.

⬐ ben_jones

Someone please tell the Google Cloud Platform teams this. So many hello world examples which reek of, "I was told to write documentation but I really hate writing documentation". I mean this in good faith, I think writing documentation for a product you don't actually use is a miserable experience and I hope they can find a better balance...

Writing documentation also seems to be a task you kick out to your junior developers that you'd rather not give more critical assignments to, which is backwards as can be.

⬐ chenhan

GCP documentation is the worst I have come across so far. The GCP documentation seems to have multiple personalities. It is as if the different parts of the documentation were written by different teams in different corners of the company.

I have to often disregard the documentation and get into the gcloud (their Python-based CLI and API) to understand what the heck is going on and their CLI/API code is no good either. Layers and layers of abstraction in their code only to make some REST API calls. The amount of over-engineering and abstraction that is present in their Python code would put even Java SimpleBeanFactoryAwareAspectInstanceFactory developers to shame.

⬐ z3t4

It's not their documentation that is bad, it's the architecture. Too many layers, and things glued together. Where you need to make additional abstractions just to make sense of it all, ending up with a million LOC just to copy something from A to B.

For example integrating support for Google Drive took months, where I ended up using a third party solution, and users are met with a big red warning about my app now being unknown. And the file system is laggy. Compared to integrating Dropbox which took three days and just works. Google Drive probably have thousands of pages of documentation. While Dropbox have one or two.

⬐ exikyut

It's a moat.

⬐ shantly

Android docs feel the same way, with a side of "eh, just make the interns do it".

⬐ te_chris

Oh god yes, so frustrating

⬐ whoisjuan

If there's one documentation that I hate with my gut, that is GCP documentation. Like wtf is going on there. Just to give you an example of how horrible it is, just check their Vision documentation: https://cloud.google.com/vision/docs/

They have quick starts, tutorials and how-to-guides. How are even those things conceptually different at all?. And their reference is just a list of their methods like if I knew out of the box how to use your API. Like, what the heck. Just tell me how to talk to your API in simple terms. How hard is it?

"To use the CGP vision API there are two ways to authenticate and connect. 1) REST 2) SDKS" and then just explain to me how to do it simply.

Don't ramble like if this was the fucking Iliad. Go straight to the point and organize your information better.

⬐ nullspace

It's possible that I'm jaded by non-existing documentation, but skimming over the docs in your link, this actually looks like an example of good documentation*

The API reference in particular you pointed to has a top-level description + linkable reference to each individual method / resource along with brief description. AND, for older versions, as well as a description of "objects" used in the API. I guess it would have been nice to also have a sandbox playground, like some of their other APIs do, but this one is fairly good?

Just curious, what's an example of great API in your mind?

*(possibly not in-depth enough, but I wouldn't be able to tell as a newbie).

⬐ styfle

In this case, google cloud vision, it seems like the docs are fine. It’s the platform that’s confusing because it requires too much ceremony to get started.

⬐ BurningFrog

Being fairly new to Python the "story format" of the documentation is one of the most frustrating things.

"This package is really good. Here is an example. This feature is cool! This other feature solves a common problem. Here is a list of some of the functions."

⬐ nl

I agree with this.

I haven't done any substantial Java work in probably 8 years and I still miss the JDK docs.

⬐ paranoidrobot

I'm hitting the same problem a lot with a bunch of things.

Concourse CI is the one I'm running up against this today - I'm taking over a partially built installation which has all sorts of hard-coded config environment variables that I'm trying to figure out their purpose.

Their documentation has basic getting-started stuff[1], but doesn't list all the config variables and their use. It's open source, so I cloned the repo, but they don't directly reference the environment variables there, either.

Compare that to, say, Ansible's documentation - it exhaustively lists all the options[2] and what they're used for, with links to other related documentation.

[1] https://concourse-ci.org/concourse-web.html [2] https://docs.ansible.com/ansible/latest/reference_appendices...

⬐ vito

(Concourse co-creator/OSS lead here.)

Our CLI hasn't really aged well and that's something I'd like to address soon - probably going more in the direction of config files instead of flags/env vars. It'd be a lot easier to document with a proper schema. Thanks for the feedback and sorry the experience is still pretty rocky!

⬐ paranoidrobot

Awesome, thanks.

Honestly the whole application seems pretty good - but everything is focussed on more hello-world stuff, which is great for getting going on my machine - not so great for running it for real.

Whether you use environment vars or a config file, I don't mind - one benefit environment vars gives is that setting CONCOURSE_BIND_IP to the instance's IP is relatively simple, eg on AWS:

CONCOURSE_BIND_IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4)

If it's a config file then I need to update that before the application starts, which is more fiddling.

⬐ vito

Yeah that's a good point. There are definite trade-offs to going for only one or the other. If there's a nice way to support both without too much maintenance overhead, that'd be my preference. There are a few popular Go libraries which support that, like https://github.com/spf13/viper - which we'll probably consider switching to as part of a general CLI overhaul.

For a long time now we've been primarily focusing on the core design, concepts, and architecture at the expense of documentation and introductory material and outreach - we've never had a dedicated technical writer, so documentation is really best-effort. Now that the dust is settling on our roadmap I feel a lot more confident in increasing our focus on onboarding, operability, and developer/user experience in this coming year. :)

⬐ jpxw

I assume you’re talking about Go here?

⬐ toyg

I wouldn't think so, docs in Go look very terse to me, not at all "story mode".

Maybe Rust or Clojure...?

⬐ shepmaster

Rust has books [1] as well as the usual terse API docs [2], so that also seems unlikely.

[1]: https://doc.rust-lang.org/stable/book/

[2]: https://doc.rust-lang.org/std/

⬐ weberc2

Unless something has changed very recently, Go docs aren't story-format.

⬐ phodge

Possibly Typescript. Try finding documentation for the bundled "Record" type. It seems you're supposed to just know how to use it already.

⬐ STRiDEX

I've heard the same typescript feedback from coworkers. Another commenter already linked to the official docs, I always link them to https://github.com/sindresorhus/type-fest#readme which has links and docs of the built in types and can be installed for more.

⬐ sli

I have yet to find a straight answer on how `declare` actually works in the Typescript docs. I had to go to Stack Overflow to learn what it's for.

The TS docs basically just say "use declare to declare [thing]" over and over, and it's only mentioned in the handbook on a page that doesn't seem to be listed in the handbook menu anywhere.[0] You have to search for it and wing it, because the search result for this just says "By Example." Notice that there is no article highlighted in the handbook menu on the left like there would be on any of the pages listed there.

[0]: https://www.typescriptlang.org/docs/handbook/declaration-fil...

⬐ crooked-v

https://www.typescriptlang.org/docs/handbook/utility-types.h...

⬐ krick

So, what's the language?

⬐ ReidZB

I read an article[0] on HN[1] recently — it talks about the different types of documentation. To quote it directly:

"Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all."

I agreed with its premise — I've found things that only have "story format" docs (i.e. explanation / how-to guides) to be really frustrating. On the other hand, if all that's available is a deep and highly particular technical reference, it's really difficult to get started sometimes.

[0] https://www.divio.com/blog/documentation/

[1] https://news.ycombinator.com/item?id=21289832

⬐ Wowfunhappy

What is the difference between a tutorial and a how-to guide?

⬐ jwhitlark

Level of previous knowledge assumed, tutorials tend to be more "starting from zero", and scope, guides tend to have a narrower focus.

⬐ 77544cec

A tutorial is to an integration test what a how-to guide is to a unit test.

⬐ tartoran

Think of how tos as recipes for different scenarios

⬐ keithnz

if you read the link he gave, it has a really good description of each...

but to summarize...

A tutorial: - is learning-oriented - allows the newcomer to get started - is a lesson

A how-to guide: - is goal-oriented - shows how to solve a specific problem - is a series of steps

⬐ Already__Taken

And as an example, Don't list how to install node.js, npm packages and ENV settings in your HAPI server tutorial

⬐ jrochkind1

I have had similar experiences with Github Actions docs, alas. Lots of pages linking to lots of other pages, none with much useful content. Keep thinking the content that will actually explain what the heck is going on is around the corner... then I realize I've wound up linked back to a page that was already in my history! Wasn't sure if the docs were assuming some kind of domain knowledge I didn't have (like maybe if I knew docker better, or had experience with circleci or something?) -- kind of reassured to hear it's not just me!

I haven't really tried to do anything with Github Actions, I start looking at the docs and think, nah, not ready yet.

It does seem like a powerful tool.

It turns out that good docs is hard and "expensive", can't be handled as an afterthought without actually investing time/resources. A powerful complex tool that took a while to develop is gonna need a similar significant investment in docs.

⬐ ethomson

Product Manager for GitHub Actions here. Sorry that this was difficult for you - we're continuing to work on our documentation for both GitHub Actions and Github Packages (and how to use them together) and we'll make sure that we improve this.

For my Java project, I set up GitHub Packages as a server in my settings.xml, and then use:

mvn deploy -Dgithub.username=${{github.actor}} -Dgithub.password=${{github.token}} -s settings.xml

as a step in my GitHub Actions workflow.

I'm not super familiar with maven, so I'll talk with the Packages team about how we can improve the documentation here.

⬐ edaemon

To provide another perspective, we were in the beta and I ran into this documentation problem (and a few others), but since then it's gotten noticeably better. Still room for improvement as this thread has covered but it seems like you're on the right track.

⬐ stevehawk

Y'all might be better served by just throwing out a chunk of what you have. When my customer said they wanted to have automated deployments of their webapp to AWS (where branch name = subdomain.dev.customer.com) it took me waaay too long to set it up. It seemed like a lot of your docs would provide examples that were already outdated based on the product being in beta. I assume they're still wrong though because I wrapped up the project 2 days before you left beta and I remember thinking "holy crap, they were that close to being live and the docs were still that bad?"

⬐ SahAssar

I've converted our teams CI/CD to use github actions (from mostly running on AWS) at a large company since early in the beta, but we have also run into a lot of issues. Where can I report these issues and get a real answer? I don't mind getting told that a certain feature is on the backburner, I just want to know that someone has considered it.

⬐ ethomson

The best place to report issues or request features is https://github.community/. The Product and Support teams both visit that regularly.

⬐ petrikapu

and worst seem to be actual support email for paying customers. I asked questions about self-hosted runners 10 days ago and still waiting (I’d like to have spool of shared runners for private repos)

⬐ stevehawk

> Github documentation is a disaster. They leave out critical parts. They don't provide examples. Everything they write is terse, confusing, and incomplete.

Agreed. A lot of times they seemed to use the ole "make a blog post about X and we'll call it documentation" strategy that a lot of others seem to be employing as well. The net result is useless documentation that is often outdated by the time a product is live. However, that doesn't change the fact that it's still the top search engine result for the topic or the de facto page many link to within their own actual 'documentation'.

⬐ TheFiend7

While I do agree with you, I've found often times a good ol blog post with an example connecting some dots can be very productive.

But I do agree with you that it's very from from being an alternative, and instead should be used to supplement healthy documentation.

⬐ stevehawk

I agree with that. I know I have also grown particularly jaded because I've read so many useless blogs as everyone is trying to push out their own Medium articles so they can get that hot new FAANG job.

⬐ hinkley

There’s a really stupid simple partial fix for this but it seems to be non obvious to a lot of people.

And that’s to watch a coworker who hasn’t used it before try to follow your docs. Try again, and then pick another coworker. By then it should be good enough for the majority to follow, and you take the rest of the questions as they come. Put the first draft out and you’ll be swamped with complaints.

⬐ kwhat4

I have had the complete opposite experience. Github actions was far easier to setup and get running than AWS CodePipeline or Jenkins. I must admit, I have not gotten down to the nitty gritty API level documentation, but for simple building & testing, it has been a godsend.

⬐ maxdo

Gitlab ci is a direct competitor and they are much more advanced for CI

⬐ ccleve

I did, in fact, get the build server to work. Posting the resulting artifacts to Github Packages has been the big problem.

⬐ jillesvangurp

Sounds a bit harsh. I managed to get a simple gradle build going a few weeks ago with very little work. I say, simple, but it actually uses docker compose to spin up Elasticsearch to run some integration tests (using the gradle docker compose plugin). This was shockingly easy and required no extra work since their ubuntu context already has that pre-installed. So, use ubuntu, checkout code, add Java, configure some caching (optional, but it helps), run build: https://github.com/jillesvangurp/es-kotlin-wrapper-client/bl...

Given that you are using maven, which can be a bit fiddly, might it be the case that some of your issues are with your build? E.g. the way maven deploy works is very dependent on how you set up the pom file.

⬐ ccleve

My build worked ok. It was the integration with Github Packages that failed.

⬐ cheesedoodle

I agree! I'm trying to migrate an OSS project from circleci to GitHub Actions but fail configure probably one of the most common actions there is: build a (cmake/c++) project inside a custom docker image. There should be a an clear and concise example of this. Even a migration example would actually be expected if GitHub wants to quickly convert users from X service to their CI.

⬐ tracker1

It's kind of ugly, but I spend a bit of time using some node scripts to orchestrate a scheduled "nightly" build of an application package that does some relatively funky stuff. See the .github/workflows and scripts/ areas... again, it's hacky. Was trying to do something that wasn't very well documented by example strictly speaking.

You can probably use another scripting language to use the github interface.

https://github.com/bbs-io/syncterm-windows

Aside, you need to pass your github token in as part of your workflow config.

https://github.com/bbs-io/syncterm-windows/blob/master/.gith...

⬐ dawnerd

My gripe with actions was the big refactor/change they made so all the old examples and apps which show up in search are wrong now.

There's also a lot of things you should be able to do but are not apparent or clear - and yeah the documentation is a disaster

⬐ xtracto

I did not get very far... I use Gitlab for personal projects and love their CI/CD process ... In my company we are using Github and were excited to start using these tools for CI/CD. But when I tried to do a simple CI action that took the code in the repo and ran npm install && npm test (simple .gitlab_ci.yml on gitlab) I could not find heads or tails on how to do it... wasn't clear if it was possible with Actions or if I need a third party like CircleCi or aws or what...

⬐ aassddffasdf

Umm, GraphQL is a reflective API-- use 'introspection': https://graphql.org/learn/introspection/

⬐ pc86

I don't think that's the point.

⬐ aassddffasdf

It's my point so what is your point?

⬐ munk-a

This same sort of introspection and auto-discovery was an original tenant of REST that's mostly ignored these days and I'm happy for that - I've never seen this sort of thing work well because it assuming you're able to translate data points into unambiguous identifiers. So the company object has a name object, I might assume that's the name of the company, but what if it's the registration number of the company - does it include legal suffixes? Maybe it's the name of the majority owner and this company object is related to the stock market. Let's take a more fun example, some sort of grocery service that lists "price" does price include tax? Is it in USD? Is the price in dollars or cents? Are all prices in the same currency? Is the price the cost to the end user or the cost to fulfill inventory on a unit basis? Does the price include discounts - if there is a "price" and "sale_percentage" column then has the sale percentage already been applied - how does that sale_percentage work, is .2 for sale_percentage mean there is a 20% or 80% discount - considering it was built by programmers it'd probably mean an 80% discount but that's not what a layman would assume.

Introspection is not valid in place of documentation.

⬐ aassddffasdf

That all comes down to how well-designed the API is. Not all APIs are created equal but in the hands of a skilled designer, this functionality is priceless. Not only that but you can also look at the actual values to tease apart any meanings that seem ambiguous (but, once again, in the hands of a good designer those won't exist in the first place).

⬐ munk-a

I've seen a lot of "self-documenting" code in my time and it can be quite legible when starting in an organization that has good discipline... The issue is that there are always some weird edge cases and poorly named things that exist because "legacy" - in those cases a quick question should clear everything up, if you have access to someone in the know.

When it comes to APIs if you're eschewing documentation it's because (I hope) you are trying to minimize support costs and thus devs using the API won't have someone to ask questions of so those edge cases become mysterious and assumptions are made that may be wrong.

If you're designing an API that serves up items that may be on sale how would you name fields so that the price and possibly sale discount are unambiguous to read?

⬐ clarkbw

Sorry you've been fighting this. We're actively working on the documentation as well as improving the setup workflows for Actions which should alleviate lots of this pain.

Those one line snippets are likely going to be taken down, most systems are too complicated for those to work. It looks nice for a couple package systems but that Maven one is obviously flawed.

I'd be happy to help you dig through whatever you're trying to do; I'm @clarkbw on twitter. I'd also love another set of eyes on the changes to the setup-java action, specifically getting Maven authentication to work well.

https://github.com/actions/setup-java/pull/29

(I'm the PM heading up the Packages project at GitHub)

⬐ mehrdadn

Hi there! Could I also ask for some documentation on the proper way to get a Windows CI system that has popular software (like Clang, MSYS2, etc.)? I know you can install these via NuGet, but it has a habit of failing a ton randomly (503 server error or other random stuff) and having to install each tool on every build slows things down a ton. I assume there must exist images that already have these? (This has been a mystery for me to figure out. I don't know if it's relevant, but I'm not a Docker user.)

⬐ jhasse

wxFormBuilder uses GitHub Actions for its MSYS2 Windows build: https://github.com/wxFormBuilder/wxFormBuilder/tree/master/....

⬐ mehrdadn

Oh man, I forgot I tried numworks/setup-msys2 earlier but I ran into some issue. I think my IP address was blocked or something for some bizarre reason (I wasn't doing anything funny...), but I'll give it a shot again, thanks.

⬐ nmerz

I am fighting with packages, too. My desire to move a package to another repo still is unanswered. No help via forum or my support requests.

https://github.community/t5/How-to-use-Git-and-GitHub/Move-N...

⬐ sniuff

They cannot move packages. They were able to delete packages in one repository and we were able to push to a new repository. The support responded every day US time.