8 ms·

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

by ccleve 7y ago

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 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 7y ago
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 7y ago
  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.
  - te_chris 7y ago
    Oh god yes, so frustrating
  - shantly 7y ago
    Android docs feel the same way, with a side of "eh, just make the interns do it".
  - whoisjuan 7y ago
    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/ 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 7y ago
      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 7y ago
        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.
- jpxw 7y ago
  I assume you’re talking about Go here?
  - toyg 7y ago
    I wouldn't think so, docs in Go look very terse to me, not at all "story mode". Maybe Rust or Clojure...?
    - shepmaster 7y ago
      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/ https://doc.rust-lang.org/stable/book/ [2]: https://doc.rust-lang.org/std/ https://doc.rust-lang.org/std/
  - weberc2 7y ago
    Unless something has changed very recently, Go docs aren't story-format.
  - phodge 7y ago
    Possibly Typescript. Try finding documentation for the bundled "Record" type. It seems you're supposed to just know how to use it already.
    - crooked-v 7y ago
      https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkt https://www.typescriptlang.org/docs/handbook/utility-types.h...
    - STRiDEX 7y ago
      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 https://github.com/sindresorhus/type-fest#readme which has links and docs of the built in types and can be installed for more.
    - sli 7y ago
- ReidZB 7y ago
  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/ https://www.divio.com/blog/documentation/ [1] https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832
  - Wowfunhappy 7y ago
    What is the difference between a tutorial and a how-to guide?
    - jwhitlark 7y ago
      Level of previous knowledge assumed, tutorials tend to be more "starting from zero", and scope, guides tend to have a narrower focus.
    - keithnz 7y ago
      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 7y ago
        And as an example, Don't list how to install node.js, npm packages and ENV settings in your HAPI server tutorial
    - 7y ago
- krick 7y ago
  So, what's the language?
- BurningFrog 7y ago
  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 7y ago
    I agree with this. I haven't done any substantial Java work in probably 8 years and I still miss the JDK docs.
- paranoidrobot 7y ago
  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 https://concourse-ci.org/concourse-web.html [2] https://docs.ansible.com/ansible/latest/reference_appendices/config.html#environment-variables https://docs.ansible.com/ansible/latest/reference_appendices...
  - vito 7y ago
    (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 7y ago
      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 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 7y ago
        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 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. :)
kwhat4 7y ago
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.
- ccleve 7y ago
  I did, in fact, get the build server to work. Posting the resulting artifacts to Github Packages has been the big problem.
- maxdo 7y ago
  Gitlab ci is a direct competitor and they are much more advanced for CI
aassddffasdf 7y ago
Umm, GraphQL is a reflective API-- use 'introspection': https://graphql.org/learn/introspection/ https://graphql.org/learn/introspection/
- pc86 7y ago
  I don't think that's the point.
  - aassddffasdf 7y ago
    It's my point so what is your point?
- munk-a 7y ago
  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 7y ago
    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).
tracker1 7y ago
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 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/.github/workflows/nightly.yml https://github.com/bbs-io/syncterm-windows/blob/master/.gith...
ethomson 7y ago
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.
- stevehawk 7y ago
  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 7y ago
  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 7y ago
    The best place to report issues or request features is https://github.community/ https://github.community/. The Product and Support teams both visit that regularly.
    - deleted 7y ago
      [deleted]
stevehawk 7y ago
> 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 7y ago
  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 7y ago
    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 7y ago
  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.
clarkbw 7y ago
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 https://github.com/actions/setup-java/pull/29 (I'm the PM heading up the Packages project at GitHub)
- mehrdadn 7y ago
  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 7y ago
    wxFormBuilder uses GitHub Actions for its MSYS2 Windows build: https://github.com/wxFormBuilder/wxFormBuilder/tree/master/.github/workflows https://github.com/wxFormBuilder/wxFormBuilder/tree/master/....
    - mehrdadn 7y ago
      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 7y ago
  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-NPM-package-to-other-repo-quot-Package-is-already/m-p/40155 https://github.community/t5/How-to-use-Git-and-GitHub/Move-N...
jrochkind1 7y ago
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.
cheesedoodle 7y ago
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.
xtracto 7y ago
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...
dawnerd 7y ago
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
jillesvangurp 7y ago
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/blob/master/.github/workflows/gradle.yml 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 7y ago
  My build worked ok. It was the integration with Github Packages that failed.

by ccleve 7y ago

ComputerGuru 7y ago

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 7y ago
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.
- te_chris 7y ago
  Oh god yes, so frustrating
- shantly 7y ago
  Android docs feel the same way, with a side of "eh, just make the interns do it".
- whoisjuan 7y ago
  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/ 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 7y ago
    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 7y ago
      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.
jpxw 7y ago
I assume you’re talking about Go here?
- toyg 7y ago
  I wouldn't think so, docs in Go look very terse to me, not at all "story mode". Maybe Rust or Clojure...?
  - shepmaster 7y ago
    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/ https://doc.rust-lang.org/stable/book/ [2]: https://doc.rust-lang.org/std/ https://doc.rust-lang.org/std/
- weberc2 7y ago
  Unless something has changed very recently, Go docs aren't story-format.
- phodge 7y ago
  Possibly Typescript. Try finding documentation for the bundled "Record" type. It seems you're supposed to just know how to use it already.
  - crooked-v 7y ago
    https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkt https://www.typescriptlang.org/docs/handbook/utility-types.h...
  - STRiDEX 7y ago
    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 https://github.com/sindresorhus/type-fest#readme which has links and docs of the built in types and can be installed for more.
  - sli 7y ago
ReidZB 7y ago
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/ https://www.divio.com/blog/documentation/ [1] https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832
- Wowfunhappy 7y ago
  What is the difference between a tutorial and a how-to guide?
  - jwhitlark 7y ago
    Level of previous knowledge assumed, tutorials tend to be more "starting from zero", and scope, guides tend to have a narrower focus.
  - keithnz 7y ago
    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 7y ago
      And as an example, Don't list how to install node.js, npm packages and ENV settings in your HAPI server tutorial
  - 7y ago
krick 7y ago
So, what's the language?
BurningFrog 7y ago
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 7y ago
  I agree with this. I haven't done any substantial Java work in probably 8 years and I still miss the JDK docs.
paranoidrobot 7y ago
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 https://concourse-ci.org/concourse-web.html [2] https://docs.ansible.com/ansible/latest/reference_appendices/config.html#environment-variables https://docs.ansible.com/ansible/latest/reference_appendices...
- vito 7y ago
  (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 7y ago
    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 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 7y ago
      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 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. :)

kwhat4 7y ago

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.

ccleve 7y ago
I did, in fact, get the build server to work. Posting the resulting artifacts to Github Packages has been the big problem.
maxdo 7y ago
Gitlab ci is a direct competitor and they are much more advanced for CI

aassddffasdf 7y ago

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

pc86 7y ago
I don't think that's the point.
- aassddffasdf 7y ago
  It's my point so what is your point?
munk-a 7y ago
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 7y ago
  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).

tracker1 7y ago

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 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/.github/workflows/nightly.yml https://github.com/bbs-io/syncterm-windows/blob/master/.gith...

ethomson 7y ago

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.

stevehawk 7y ago
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 7y ago
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 7y ago
  The best place to report issues or request features is https://github.community/ https://github.community/. The Product and Support teams both visit that regularly.
  - deleted 7y ago
    [deleted]

stevehawk 7y ago

> 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 7y ago
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 7y ago
  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 7y ago
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.

clarkbw 7y ago

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 https://github.com/actions/setup-java/pull/29 (I'm the PM heading up the Packages project at GitHub)

mehrdadn 7y ago
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 7y ago
  wxFormBuilder uses GitHub Actions for its MSYS2 Windows build: https://github.com/wxFormBuilder/wxFormBuilder/tree/master/.github/workflows https://github.com/wxFormBuilder/wxFormBuilder/tree/master/....
  - mehrdadn 7y ago
    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 7y ago
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-NPM-package-to-other-repo-quot-Package-is-already/m-p/40155 https://github.community/t5/How-to-use-Git-and-GitHub/Move-N...

jrochkind1 7y ago

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.

cheesedoodle 7y ago

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.

xtracto 7y ago

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...

dawnerd 7y ago

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

jillesvangurp 7y ago

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/blob/master/.github/workflows/gradle.yml 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 7y ago
My build worked ok. It was the integration with Github Packages that failed.